RustでCodexを使う方法｜Cargo検証と安全なコード修正手順

RustでCodexを使う価値と、今始める理由

Rustはコンパイラが型、所有権、借用、ライフタイムの問題を具体的な診断として返すため、Codexと相性のよい言語です。Codexが提案した変更に対し、cargo checkが高速なフィードバックを返し、cargo testが期待する動作を確認します。モデルの回答だけを信頼するのではなく、コンパイラとテストを判定役に置ける点が大きな利点です。

2026年7月22日にはCodex CLI 0.145.0が安定版として公開され、長い会話や出力の表示応答、会話の再開、差分確認に関わる使い勝手が改善されました。大きなRustプロジェクトでは調査結果やコンパイル診断が長くなりやすいため、この改善は実務上の追い風です。更新内容はOpenAI Codex公式リリースで確認できます。

ただし、最新版へ上げただけでRust特有の判断が不要になるわけではありません。公開APIの互換性、unsafeを許す範囲、機能フラグの組み合わせ、対応するRust版などはプロジェクト側の条件です。Codexが迷わないよう、これらを依頼文とAGENTS.mdへ書き、Cargoの結果で検証する設計が必要です。

CodexとCargoの役割を分けて考える

Codexはリポジトリ内のコードを調べ、変更案を作り、ローカルにある開発コマンドを実行できます。公式のCodex CLIドキュメントでも、ローカルリポジトリを調査し、ファイルを編集し、導入済みのツールを実行する使い方が示されています。一方、型の正しさを判定するのはrustc、packageと依存関係を扱うのはCargo、期待する振る舞いを判定するのはテストです。

この分担を曖昧にすると、「それらしいコードはできたがビルドできない」「一つのテストだけ通り、別の機能フラグで失敗する」といった状態が起きます。Codexには調査、編集、検証結果の要約を任せ、最終判断は差分とCargoの出力を見て行います。人が確認する地点を残すことが、Rustの安全性を活かす近道です。

Step 1: 目的を一つの失敗や変更へ絞る

最初に「何を直すか」を一文で示します。たとえば「parser packageで空入力時に返るエラー型を統一する」のように、対象と期待結果が読める形にします。性能改善、API整理、依存関係更新を同時に頼むと、失敗時に原因を分けにくくなります。一度の依頼では一つの目的に絞り、必要なら次の依頼へ分けましょう。

Step 2: 変更してよい範囲と維持する条件を書く

対象ディレクトリ、変更可能なファイル、触れないpackage、維持する公開関数を明記します。Rustでは小さな型変更が複数crateへ広がることがあるため、「公開APIは変更しない」「新しい依存関係は追加しない」「unsafeブロックは増やさない」といった境界が有効です。条件が競合した場合は、編集前に説明を求める一文も添えます。

Step 3: 検証コマンドを完了条件にする

依頼の最後に、実行してほしいコマンドと報告形式を書きます。単一packageならcargo check -p package名とcargo test -p package名、全体へ影響する変更なら--workspaceを使います。成功したコマンドだけでなく、未実行の検査とその理由も報告させると、確認漏れを見つけやすくなります。

RustプロジェクトでCodexを始める準備

準備では、Codexの設定より先に、手元のRustプロジェクトが現在どの状態かを確かめます。既に失敗しているテストを知らずに変更を始めると、今回の修正が原因なのか、開始前からの問題なのかを判断できません。使用するRust版、Workspace構成、主要な機能フラグ、基準となる検査結果を先に残します。

Step 1: RustとCargoの版を確認する

リポジトリのルートで次のコマンドを実行し、利用中の版を確認します。rust-toolchain.tomlやrust-toolchainがある場合は、その指定も読みます。チーム内で版が揃っていないと、診断内容や利用可能な言語機能が変わるため、Codexへの依頼にも「リポジトリ指定のtoolchainを使う」と書いておくと安心です。

rustc --version
cargo --version

Step 2: 変更前の基準を記録する

まずcargo checkを実行し、必要に応じて対象packageのテストも動かします。cargo checkは最終的なコード生成を省きながらローカルpackageと依存関係を検査するため、cargo buildより早く型エラーを探せます。ただしコード生成時だけ現れる問題は検出しない点に注意が必要です。詳細はRust公式のcargo checkリファレンスで確認できます。

cargo check
cargo test -p package名

開始時点で失敗があるなら、エラーの先頭だけでなく、実行コマンド、終了状態、失敗したテスト名を記録します。Codexには「この失敗は開始前から存在する」と伝え、今回の対象と混同しないようにします。

Step 3: AGENTS.mdへRust固有の約束を書く

Codexは作業開始前にAGENTS.mdを読み、ルートから現在のディレクトリまでの指示を重ねて適用します。詳しい探索順と優先順位はOpenAI公式のAGENTS.md解説に記載されています。Rust向けには、最低対応版、整形、lint、テスト、公開API、unsafeの扱いを書くと効果的です。

# Rust project guidance

- リポジトリ指定のRust toolchainを使う
- 変更後はcargo fmt --checkを実行する
- 対象packageでcargo checkとcargo testを実行する
- 公開APIを変える前に影響範囲を説明する
- unsafeブロックを新設しない

長大な設計書をそのまま貼るより、毎回守る短い約束を置きます。package固有の条件がある場合は、そのディレクトリに近いAGENTS.mdへ限定して書くと、無関係なcrateへ条件が広がりません。

Codexへ渡すRust修正依頼の書き方

良い依頼は、目的、対象、制約、検証の四つを短く含みます。実装方法まで細かく固定すると、既存設計に合う別案を見逃すことがあります。一方で目的だけでは範囲が広がります。守る条件は明確にし、実装の選択には調査の余地を残すのがバランスのよい頼み方です。

Step 1: 先に調査結果を出してもらう

編集前に、関係する型、呼び出し元、既存テストを特定してもらいます。「変更せず、関連ファイルと失敗経路を説明して」と頼めば、Codexの理解と自分の認識を比較できます。特にライフタイムや非同期処理に関わる変更は、局所的なエラーでも設計上の前提が複数ファイルにまたがるため、先に読み取りだけを区切ると安全です。

Step 2: 最小差分で修正を依頼する

調査結果に納得したら、変更範囲を指定して実装を頼みます。たとえば「公開関数のシグネチャは維持し、既存のエラー型を再利用し、新しい依存関係を加えずに修正する」と書きます。リファクタリングを同時に行わない条件も有効です。差分が小さければ、借用関係の変化や余分なcloneの追加も見つけやすくなります。

Step 3: 結果を四点で報告してもらう

最後に、変更したファイル、修正理由、実行した検証、残る懸念の順でまとめてもらいます。手元でコマンドを再実行するとき、どの条件を再現すべきかが分かります。失敗が残る場合は、推測で成功扱いにせず、失敗したコマンドと最初の原因を分けて書かせることが重要です。

依頼文は次の形にすると、単一crateでもWorkspaceでも再利用できます。

parser packageの空入力エラーを既存のParseErrorへ統一してください。
公開API、新しい依存関係、unsafeの数は変えないでください。
編集前に関係する型・呼び出し元・既存テストを確認し、最小差分で修正してください。
完了後にcargo fmt --check、cargo check -p parser、cargo test -p parserを実行し、
変更ファイル、理由、検証結果、残る懸念を報告してください。

Cargoで検証する順番

Rustの修正では、速く失敗する検査から順に実行すると効率的です。整形、型検査、対象テスト、全体テストの順に進めれば、単純な差分や型エラーを先に除けます。Codexにすべて任せた場合も、最終結果だけでなく各コマンドの終了状態を確認し、必要なら自分の端末で同じ順番を再現します。

Step 1: cargo fmt --checkで整形差分を見る

cargo fmt --checkはファイルを書き換えず、Rustfmtの規則との差を検査します。整形だけの大量差分が実装変更へ混ざるとレビューしにくいため、対象を限定した修正ほど先に確認する価値があります。失敗した場合は、意図したファイルだけにcargo fmtを適用できるかを確認し、無関係な既存差分まで整形しないようにします。

cargo fmt --check

Step 2: cargo checkで型と依存関係を確認する

単一packageの変更なら-pで対象を絞り、共通crateを変えた場合は--workspaceで全memberを確認します。cargo checkが通ってもリンク時やコード生成時の問題が残る可能性はあるため、ここは完成判定ではなく高速な第一関門です。機能フラグが重要なプロジェクトでは、既定設定以外の代表的な組み合わせも明記します。

cargo check -p parser
cargo check --workspace

Step 3: cargo testで振る舞いを確認する

cargo testは単体テスト、結合テスト、ドキュメントテストをコンパイルして実行します。Rust公式のcargo testリファレンスでは、テスト名による絞り込みやpackage選択の挙動も確認できます。まず変更に近いテストを動かし、その後にpackage全体、必要ならWorkspace全体へ広げます。

cargo test -p parser empty_input
cargo test -p parser
cargo test --workspace

一件の対象テストだけが通っても、別の入力やドキュメント例が壊れている場合があります。Codexには新しい回帰テストを追加する理由を説明させ、既存テストの削除や期待値の緩和で通していないことを差分で確認します。

Cargo Workspaceで対象を迷わせない方法

Cargo Workspaceは、関連する複数packageが共通のCargo.lockと出力先を使う構成です。Rust公式のCargo Workspaces解説では、ルートCargo.tomlの[workspace]とmembers、共通のtargetディレクトリという基本構造が示されています。Codexへ頼むときも、このルートとmemberの関係を基準にします。

Step 1: Workspaceルートと対象packageを明記する

「ルートのCargo.tomlを基準にし、parserだけを変更する」のように書きます。現在のディレクトリがmember内部だと、検査対象が意図より狭くなることがあります。ルートから実行するコマンドを指定し、package名はディレクトリ名ではなくCargo.tomlのpackage.nameで確認させます。

Step 2: 依存方向を確認してから共通crateを変える

共通crateの型やtraitを変えると、多数のmemberへ影響が広がります。Codexには依存するpackageを先に列挙させ、公開面を保てるかを説明してもらいます。影響が大きい場合は、互換用の関数を残す、呼び出し側を段階的に変えるなど、差分を分割できる案を比較してから編集へ進みます。

Step 3: package検査からWorkspace全体へ広げる

最初から全memberのテストを繰り返すと時間がかかり、問題の位置も見えにくくなります。変更したpackageでcargo checkとcargo testを通し、共通部分へ触れたときだけ--workspaceへ広げます。ただし最終確認の範囲はプロジェクトの規約を優先し、全体テストが必須なら省略しません。

Rust特有の注意点をCodexへ伝える

Rustのコンパイルエラーは具体的ですが、エラーを消す方法が設計上の最善とは限りません。過剰なcloneで所有権問題を回避したり、公開型を安易に変えたりすれば、コンパイルは通っても性能や互換性を損ないます。変更前に守る性質を書き、結果をコードとベンチマーク、テストで確かめます。

所有権とライフタイムは意図を先に書く

借用エラーの修正では、データを誰が所有し、参照がどこまで生きるべきかを説明します。「cloneを増やさずに直す」「返り値が入力を借用する設計を維持する」といった条件が役立ちます。Codexが提案したライフタイム注釈は、エラーを抑えるためだけでなく、呼び出し側の使い方と一致するかを確認します。

unsafeは件数ではなく安全条件を見る

既存のunsafeを変更する場合は、呼び出し側が守る条件、不変条件、境界チェックの場所を先に説明させます。新しいunsafeでコンパイラの検査を迂回する案は、代替案と必要性が示されるまで採用しません。テストが通ることだけでは未定義動作がない証明にならないため、対象を小さく保ち、レビュー可能な根拠をコメントへ残します。

機能フラグと対象環境を固定する

機能フラグにより依存関係や実装が切り替わるcrateでは、既定設定だけの成功で判断できません。サポートする代表的な組み合わせ、対象OS、最小Rust版を依頼に含めます。すべての組み合わせを検査できない場合は、実行した範囲と未確認の範囲を分けて報告させ、公開前の確認項目として残します。

よくある失敗と立て直し方

Codexが大きな変更を始めたり、Cargoの出力が長くなったりしたときは、追加の指示を重ねる前に目的を小さく戻します。失敗したコマンド、最初に現れた根本原因、今回変更したファイルを切り分ければ、会話が長くなっても判断材料を保てます。0.145.0の表示改善は助けになりますが、依頼の範囲管理そのものを代替するものではありません。

コンパイルエラーが増えた場合

最初のエラーから確認し、共通型やtraitの変更が連鎖していないかを見ます。エラーを一括で消すよう頼むのではなく、変更前の公開面へ戻せるか、対象package内で収められるかを質問します。修正が別packageへ広がるなら、一度編集を止め、影響範囲の一覧と代替案だけを出してもらいます。

検査が長時間終わらない場合

全体検査を続ける前に、対象packageとテスト名へ絞ります。依存関係の初回ビルド、ドキュメントテスト、外部資源を使う結合テストなど、時間のかかる地点を区別します。単に待つのではなく、どのコマンドが動いているか、どこまで出力されたかを確認し、必要なら人が中止を判断します。

差分が依頼範囲を超えた場合

無関係な整形、依存関係更新、命名変更が混ざったら、その変更を残す理由を一件ずつ確認します。説明できない差分は採用せず、目的に必要な変更だけへ戻します。最終的にはファイル数ではなく、要求した振る舞いと検証結果に対応する差分だけが残っているかを見ます。

まとめ

RustでCodexを活用する要点は、Codexにコードを書かせることではなく、Cargoが判定できる小さな完了条件を渡すことです。リポジトリの構造を調べ、対象packageと守る条件を定め、最小差分で編集し、cargo fmt --check、cargo check、cargo testの順に確認します。

単一crateでは対象を狭く、Cargo Workspaceではルートとmemberの関係を明記します。所有権、ライフタイム、unsafe、機能フラグは、コンパイル成功だけでは十分に判断できない領域です。公式ドキュメントとプロジェクト固有の指示を組み合わせ、差分とコマンド結果を人が確認することで、Codexの速さとRustの安全性を両立できます。