Codex の使い方 — CLI・アプリ・VSCode の選択と指示の書き方

Codex の 3 つのインターフェース — 何が違い、どれを選ぶか

Codex が提供するインターフェースは CLI・アプリ・VSCode 拡張の 3 種類あり、それぞれ操作の起点と対象となる開発スタイルが異なる。自分の開発環境と日常の作業の流れに合ったものを選ぶことが、Codex を効果的に使い続ける出発点になる。インターフェースを後から切り替えることも難しくないため、まずは自分の主な作業環境に近いものから試してみるのがよい。

Codex CLI — ターミナルから直接コード変更を指示する

Codex CLI は npm install -g @openai/codex でインストールでき、ターミナルから codex コマンドを打って起動する。ローカルのプロジェクトディレクトリで動作し、ファイルを読み込み、テストを実行し、変更を加えた上で差分として返す流れが基本だ。Git リポジトリに直接コミットするか、パッチとして出力する形も選べる(出典: https://github.com/openai/codex )。

CLI の強みは、ターミナルを普段の作業の中心にしている開発者にとってコンテキストスイッチが少ない点だ。エディタを開かずにバグ修正やテスト追加を依頼して結果を確認するまでをターミナル内で完結できる。2026年6月時点の安定版は 0.139.0 で、プレリリースとして 0.140.0-alpha 系が並行して開発中となっている(出典: https://github.com/openai/codex/releases )。

コマンドラインに慣れていて、手元のコードベースを直接操作したい場面では CLI が最も直感的な選択肢になる。ローカルにリポジトリがクローン済みの状態で動くため、プライベートなコードベースに対しても素早く使い始められる。

Codex アプリ — ブラウザから GitHub リポジトリへタスクを投じる

Codex アプリはブラウザから利用するエージェントで、GitHub アカウントのリポジトリと接続して使う。アプリにアクセスして対象リポジトリを選び、テキストでタスクを入力するだけで、Codex がクラウド上のサンドボックスでリポジトリを読み込み、コードを変更し、テストを実行して差分を返す形になっている。結果は Pull Request の形で提出されることが多い(出典: https://openai.com/codex )。

アプリはデスクトップ・スマートフォンを問わず使えるため、「移動中にモバイルから修正を依頼してオフィスに着いたら確認する」という使い方も現実的だ。複数タスクを並行して走らせることができ、それぞれの進捗をサイドバーで一覧できる仕組みになっている。CLI と異なり、ローカル環境のセットアップを必要としないのも特徴で、チームメンバー全員が同じインターフェースを使いやすい点でも導入しやすい。

VSCode 拡張 — エディタを離れずに AI 支援を使う

Codex in VSCode は VSCode のマーケットプレイスから導入でき、エディタ上のコードを選択してその場で Codex に依頼できる形が特徴だ。ファイルを開いたまま「この関数にエラーハンドリングを追加してほしい」という形で依頼でき、Codex の返答が差分として提案される(出典: https://developers.openai.com/codex )。

エディタに統合されているため、コードと自分の指示が同一画面に収まり、差分も即座に確認できる。特定のファイルやコードブロックを選択した状態で依頼を送れるため、「このコードに対して」という文脈を暗示的に伝えやすい点が利点だ。CLI やアプリが「プロジェクト全体を対象に動く」のに対し、VSCode 拡張は「今開いているファイルを起点に動く」という感覚に近く、ピンポイントな修正や補完に向いている。

Codex に効果的な指示を書く方法

指示の精度が Codex の出力の質に直結する。曖昧な指示でも Codex はとりあえず動くが、意図からずれた変更をすることがある。修正の往復回数を最小化するために、指示を書くときの基本パターンを押さえておくと実際の作業効率が上がる。特に慣れないうちは、指示が長くなるのを恐れずに情報を詰め込む方向で書くのがよい結果につながりやすい。

具体性を高める三要素 — 何を・なぜ・どこまで

効果的な指示には「何を変えてほしいか」「なぜその変更が必要か」「変更範囲をどこまで期待するか」の三点が含まれている。たとえば「バグを直して」という指示より、「src/api/client.ts の fetchUser 関数が 404 エラー時に例外を投げずに null を返している。404 の場合は UserNotFoundError を投げるように修正し、呼び出し元のテストも合わせて更新してほしい」という形のほうが、Codex が判断しなければならない余地を大幅に減らせる(出典: https://developers.openai.com/codex/guides/best-practices )。

制約の明示も重要だ。「既存のインターフェースは変えないこと」「新しい npm パッケージは追加しないこと」「テストは Jest を使うこと」という制約を添えると、Codex が不必要な変更に踏み込むのを防げる。制約がないと、Codex が「より良い方法」と判断した別のライブラリを導入したり、インターフェースを変えてしまうことがある。背景と制約をセットで伝える習慣を持つと、承認前の差分確認でサプライズが減る。

エラー情報をそのまま活用する

デバッグ系のタスクでは、発生しているエラーの全文をそのまま指示に含めることが効果的だ。「テストが落ちている」という説明だけより、「以下のエラーが出てテストが失敗している：(エラー全文)」という形のほうが、Codex が原因を絞り込みやすくなる。コピー&ペーストで対応できるため手間は少なく、Codex が参照できる情報量は大きく上がる。

実行環境の情報(Node.js バージョン、OS の種類など)を添えるとさらに有効なケースがある。Codex はサンドボックス内でコードを実際に実行しながら原因を探るため、環境依存の問題ほど背景情報が役立つ。ログの全文をトリミングせずに貼ることを意識するだけで、Codex の診断精度が上がりやすい。スタックトレースが長くても省略せず全文を渡すことを推奨する(出典: https://developers.openai.com/codex/guides/best-practices )。

大きなタスクは段階に分けて依頼する

「認証ミドルウェアを刷新する」のような大規模な変更を一度に依頼すると、Codex が見当違いの方向に進んだり、変更範囲が広くなりすぎて確認が困難になることがある。こうした場合は段階的に進めることを推奨する。

1. まず「現状の認証フローとコード構造をまとめたドキュメントを生成してほしい」と依頼して内容を確認する
2. 次に「認証関数の単体テストカバレッジを上げてほしい」と続けてテストを先に整える
3. 最後に「テストを維持しながらミドルウェアのロジックを刷新してほしい」と依頼する

段階的な依頼は、1 回のタスクで変更されるファイル数が自然に絞られるため差分の確認もしやすくなる。問題があったときの影響範囲も限定できる。大きな変更を一気にやらせるより、小さな変更を積み重ねる方針のほうが最終的にスムーズに進みやすい傾向がある。

出力を確認して修正・承認するサイクル

Codex がタスクを終えた後、差分と実行ログを確認してから承認するプロセスが品質維持の要になる。確認をスキップすると、意図と異なる変更やテスト未実施の状態でコードがマージされるリスクが生じる。慣れてくると確認の時間は短くなるが、最初のうちは差分とログを丁寧に読む習慣をつけることを優先したい。

差分ビューとログを確認する

Codex の出力には、変更されたファイルごとの差分と実行ログが含まれる。差分ビューでは削除された行が赤、追加された行が緑で示され、変更全体の意図が把握しやすい形で表示される。確認のポイントは「依頼の意図と変更が一致しているか」「想定外のファイルが変更されていないか」「必要なテストが追加・更新されているか」の三点だ(出典: https://developers.openai.com/codex/guides/how-codex-works )。

実行ログには、Codex がタスク中に実行したコマンドとその出力が時系列で記録されている。テストの実行結果、インストールしたパッケージ、コンパイル時のエラーなどが含まれるため、Codex がどのような手順を踏んだかを後から追える。テストが失敗しているにもかかわらず Codex が承認を求めてきた場合でも、ログを読むことでどのテストがどのエラーで落ちているかを把握できる。

追加されたテストの内容を丁寧に読むことも重要だ。テストが形式的に書かれているだけで、実際の問題をカバーしていないケースがある。コードの変更内容だけでなく、テストの質も含めて判断することで、マージ後に問題が残るリスクを減らせる。

追加指示で修正を続ける

差分に問題がある場合や、テストが通っていない場合は、承認せずに追加指示を出してサイクルを続ける。「差分の○○ファイルの変更は意図と異なる。○○の仕様を維持したまま修正してほしい」という形の具体的なフィードバックが効果的だ。「修正してほしい」だけでは Codex が何をどう変えるべきか判断しにくい。

追加指示のコツは、Codex が生成した出力の具体的な部分を引用して指摘することだ。エラーメッセージや差分の特定箇所をそのまま参照すると、Codex が問題箇所を正確に特定しやすくなる。修正サイクルを重ねるうちに、Codex が以前の指示の文脈を保持した上で変更を加えていく仕組みになっている(出典: https://developers.openai.com/codex )。

CLI でセッションを再開してコンテキストを引き継ぐ

CLI では codex --resume オプションを使うことで前回のセッションのコンテキストを引き継いで作業を続けられる。作業途中で中断しても、Codex がどこまで何をしたかのコンテキストを保持しているため、「前の続きから始めて」という指示で再開できる。長い修正を複数のターンにまたいで進める場合に特に有効だ(出典: https://github.com/openai/codex )。

アプリでは、サイドバーのタスク一覧から過去のタスクを選ぶと、Codex がそのタスクで行った変更と指示の履歴を参照した上で追加指示を受け付ける形になっている。タスクをいったん閉じても、一覧から再度開いて指示を追加できる。「昨日の続きを今日やる」という形の作業分割も実際の開発では起こりやすく、セッションの再開機能を活用することで作業の継続性を維持しやすい。

用途別の実践的な操作パターン

Codex の基本的な使い方を踏まえた上で、実際の開発で頻出するシーン別の操作パターンを紹介する。指示の書き方、確認のポイント、よくある注意点をシーンごとに整理した。

バグ修正の依頼パターン

バグ修正を依頼するときは、「バグが発生している状況」「再現手順または失敗しているテスト名」「期待する動作」を指示に含める。エラーメッセージがあれば全文を貼り、対象のファイルや関数がわかっていれば明示する。「テストも含めて修正してほしい」という一言を添えることで、修正とテストをセットで返してもらいやすくなる。

1. 失敗しているテスト名またはエラーメッセージを指示に全文貼り付ける
2. 対象のファイルと関数名がわかれば明示する
3. 「既存のテストと同じスタイルでテストを追加または更新してほしい」と制約を添える
4. 差分とテスト実行ログを確認して、テストが通っていることと意図に沿った変更かを確認してから承認する

承認後に問題が見つかった場合でも、ログを参照した上で追加指示を出すことで修正を続けられる。一度のタスクで完璧にならなくても、反復の中で目標に近づける(出典: https://developers.openai.com/codex/guides/best-practices )。

新機能追加の段階的な依頼パターン

新機能の追加は、一度に全部やらせようとせず、設計の確認から始めて段階的に進めるとコントロールしやすい。まず「この機能をどのファイルにどのような形で実装するか、変更方針をまとめてほしい」と依頼して Codex の認識を確認する。方針が意図と合っていることを確認してから実装の依頼に進む手順が安全だ。

1. 実装方針の整理を先に依頼して出力を読む
2. 方針が意図と合っていれば実装を依頼する
3. 「テストも同時に作成すること」「既存インターフェースは変えないこと」という制約を明示する
4. 差分を読んで想定外の変更がないかを確認してから承認する

特に規模の大きな機能追加では、一回の依頼で変更されるファイル数を 5 個程度までに抑えることを目安にすると、差分の見通しがよくなる。

テストカバレッジを上げる依頼パターン

既存コードのテストを追加させる場合は、対象モジュールを絞って依頼するのがよい。「src/utils/ 配下のすべての公開関数について、未テストの分岐やエッジケースをカバーするテストを追加してほしい。テストフレームワークは Jest で、既存のテストファイルのスタイルを踏襲すること」という形で対象と制約を指定する。

追加されたテストが形式的なものでないかを差分で確認することが重要だ。テスト名と assert の内容を読んで、実際に意味のあるカバレッジが増えているかどうかを判断してから承認するとよい。テストの内容が薄かった場合は「期待値が一つしかないテストは、複数の境界値を追加してほしい」という具体的な追加指示で品質を上げられる(出典: https://developers.openai.com/codex/guides/best-practices )。