Codex CLIを実務へ入れる―チャットと違うローカル作業と便利な3つの機能

AIへコードを聞くこと自体は、ブラウザのチャットでもできる。

数十行のコードを貼って、「ここを直して」と頼むだけなら、それで十分なことも多い。

ただ、対象が既存プロジェクトになると少し面倒になる。

関係するファイルを探して、コードを貼る。エラーが出たらログを貼る。修正案を受け取ったらローカルへ反映し、テスト結果をまた渡す。

作業が長くなるほど、人間がAIとローカル環境の間を往復する回数が増える。

Codex CLIは、この部分をターミナル側へ持ってくる。

OpenAIの現在の公式ドキュメントでは、Codex CLIはローカルリポジトリを調査し、ファイルを編集し、端末に入っているツールを実行できるコーディングエージェントとして案内されている。

※ 図は仕組みを説明するための概念図で、実際のCodex画面ではない。

チャットとの違いはローカル環境との距離#

Codex CLIは、作業させたいリポジトリでcodexを起動して使う。

npmから入れる場合は次の形。

npm i -g @openai/codex

インストール後、対象プロジェクトへ移動して起動する。

cd my-project
codex

初回はChatGPTでのサインインなど、利用可能な認証方法を選ぶ。

この時点でブラウザのチャットとかなり違う。

チャットへコードを貼るのではなく、Codex側が現在のディレクトリを見て、必要なファイルを探せる。変更が必要ならファイルを編集し、npm testやnpm run buildのようなローカルコマンドも同じ流れで実行できる。

例えば、

このAPIのタイムアウト処理を確認。
影響するファイルを調査して修正し、
既存テストと追加したテストを実行。
最後に変更点を説明して。

という単位で渡せる。

人間側が「次はこのファイル」「次はこのログ」と毎回貼り直す作業を減らせるのが、CLIで使う意味になる。

もちろん、AIがローカルファイルへ触れる以上、実行権限は別に考える必要がある。Codex CLIには/permissionsがあり、編集やコマンド実行をどこまで許可するかを切り替えられる。

OpenAIのドキュメントでも、無人実行でワークスペース内に収まる作業ならworkspace-writeを使い、承認とsandboxを完全に迂回する設定は専用のsandbox VM以外では避けるよう案内している。

便利だから全部許可する、ではなく、作業範囲に合わせて権限を決める方が扱いやすい。

実務で使うなら便利なのはこの3つ#

Codex CLIには画像入力、Web検索、MCP、subagents、セッション再開など複数の機能がある。

その中で、日常の開発へ入れやすいのはAGENTS.md、レビュー、codex execの3つ。

単発でコードを書かせる機能より、「毎回同じ注意を言わなくてよい」「変更後を確認できる」「対話を自動処理へ持っていける」という部分の方が実務では効きやすい。

1. AGENTS.mdでプロジェクトのルールを固定する#

Codexは作業前にAGENTS.mdを読む。

プロジェクトごとに、

# AGENTS.md

## Repository rules

- JavaScriptを変更したらnpm testを実行する
- 新しい本番依存パッケージを追加する前に確認する
- public APIを変更した場合はdocsも更新する
- 既存の命名規則を維持する

のようなルールを書いておける。

ブラウザチャットでは、新しい会話を始めるたびに「テストも実行して」「勝手に依存関係を増やさないで」と説明することがある。

AGENTS.mdへ入れておけば、そのリポジトリでCodexを使うときの前提にできる。

現在の公式仕様では、Codex homeにあるグローバルなAGENTS.mdと、プロジェクト内のAGENTS.mdを重ねて読み込む。プロジェクトルートから現在の作業ディレクトリへ向かって探索し、より近いディレクトリの指示を後から適用する。

用途別にルールを分けることもできる。

project/
├─ AGENTS.md
├─ frontend/
│  └─ AGENTS.md
└─ services/
   └─ payments/
      └─ AGENTS.override.md

リポジトリ全体のルールはroot。

決済処理だけ別のテストコマンドを使うなら、その近くへoverrideを置く。

同じ説明をプロンプトへ何度も書かなくてよいので、長く使うプロジェクトほど効果が出やすい。

ただし、何でも書けばよいわけではない。

長い設計書をそのまま詰め込むより、変更してよい範囲、必須のテスト、禁止する変更、使用するコマンド、命名や配置のルールくらいを短く書く方が使いやすい。

2. /reviewで変更後の確認を別工程にする#

コードを書かせたあと、そのまま終わりにしないための機能として/reviewがある。

CLIから対話的にレビューできるほか、codex reviewを直接実行することもできる。

未コミットの変更を対象にするなら、

codex review --uncommitted

特定のbase branchとの差分なら、

codex review --base main

commit単位なら、

codex review --commit <SHA>

という形。

OpenAIの現在のCLIドキュメントでは、レビューは変更を直接書き換えるのではなく、優先度を付けた指摘を返す処理として説明されている。

修正を依頼した同じ流れの中で、

実装
↓
テスト
↓
差分レビュー
↓
必要なら追加修正

まで進められる。

人間側も、最終的にはgit diffやテスト結果を見る必要がある。ただ、先に機械的なレビューを1回挟めるので、単純な見落としを拾う工程を追加しやすい。

既存コードのリファクタリングでは、機能追加の成否だけでなく、既存処理を壊していないか、エラーハンドリングが抜けていないか、テスト対象が不足していないか、変更範囲が必要以上に広がっていないか、といった観点をレビューへ渡せる。

3. codex execで対話を繰り返し処理へ移す#

最初は対話型のcodexだけでも十分使える。

ただ、同じ種類の作業を何度も行うようになるとcodex execが使える。

codex execは非対話モード。

codex exec "未コミット差分を確認し、問題があれば報告して"

のように、1つの処理として実行できる。

標準入力から指示を渡すこともできる。

type task.txt | codex exec -

WindowsのPowerShellなら、例えば次のような形でも渡せる。

Get-Content .\task.txt | codex exec -

対話を待たずに完了するため、スクリプトやCIへ組み込みたいときに使いやすい。

公式CLIリファレンスでも、codex execは人間との対話なしで完了するスクリプト・CI向けの実行方法として位置付けられている。

例えば毎回同じ確認をするなら、

ビルド
↓
テスト
↓
差分確認
↓
Codexによる追加レビュー

の一部へ入れられる。

最初は対話で試し、同じ指示を何度も使うようになったらcodex execへ移す。この順番なら、いきなり大きな自動化を作らずに済む。

画像やWeb検索もターミナルから追加できる#

コードだけで説明しにくい作業では、画像も入力できる。

公式ドキュメントではcodex --imageでスクリーンショットや構成図を最初のpromptへ渡せるほか、対話中に画像を貼り付ける方法も案内されている。

Webの最新情報が必要ならcodex --search。

外部サービスや社内ツールを接続する場合はMCP。

大きな調査を分けたい場合はsubagents。

CLIだから文字だけ、という状態ではない。

ただ、普段のコード修正で毎回全部を使う必要はない。ローカルのコードとテストで完結する作業なら、それだけで十分。

AIに任せる範囲を先に決める#

Codex CLIはローカルのファイルを編集し、コマンドも実行できる。

チャットより作業へ近い分、間違った指示の影響も大きくなる。

特に注意したいのは、本番環境への操作、DBの破壊的変更、秘密情報を含むファイル、認証情報、外部サービスへの書き込み、大量ファイルの一括変更のような処理。

/permissionsで実行範囲を確認し、Gitのcheckpointを作ってから作業を始める方が戻しやすい。OpenAIのクイックスタートでも、タスクの前後にGit checkpointを作ることが推奨されている。

例えば、

調査は自由
↓
workspace内のコード修正は許可
↓
テスト実行も許可
↓
外部への書き込みは確認
↓
commitとpushは人間が確認

くらいでも十分使える。

この境界はプロジェクトによって変わる。

Codex CLIはチャットを置き換えるものではない#

設計相談や技術比較だけなら、ブラウザのチャットの方が楽なこともある。

Codex CLIが向いているのは、話の中心がローカルリポジトリにある作業。

既存コードを調べる。複数ファイルを直す。テストを回す。diffを見る。レビューする。同じ処理を繰り返す。

こういう作業になると、ファイルとAIの間を人間が中継しなくてよい差が出てくる。

AGENTS.mdでルールを固定する。

変更後は/reviewで確認する。

繰り返せる処理はcodex execへ移す。

この3つだけでも、Codex CLIを「ターミナルで使えるチャット」ではなく、開発フローの一部として扱いやすくなる。

まずは既存リポジトリで、影響範囲の小さい修正から使うのがよい。

AIへ全部任せるのではなく、調査・修正・テスト・レビューのどこを任せるかを決めて使う。その方が実務の開発手順へ入りやすい。

参考#

• OpenAI Codex CLI
• OpenAI Codex CLI Developer commands
• OpenAI Custom instructions with AGENTS.md
• OpenAI Codex