Codex エージェントとして使う方法：自律実行の設定と活用例

Codex がエージェントとして動く仕組み

Codex アプリや Codex CLI でタスクを投入すると、Codex は次の工程を自律的に繰り返す。まずリポジトリの構造を把握するためにファイルツリーを走査し、関連するファイルを特定する。次に作業計画を内部で立て、コードを書き始め、テストを実行する。テストが失敗すればスタックトレースを読み取って修正を行い、再度テストを走らせる。この「実行→観察→修正」サイクルを繰り返し、成功が確認できた時点で変更内容をまとめて報告する。

このサイクルを支えているのは、Codex が動作するサンドボックス環境だ。ファイルの読み書き、ターミナルコマンドの実行、ウェブ検索（v0.142.0 以降はインデックス付き検索に対応）がこのサンドボックス内で完結する。ユーザーのローカル環境を直接汚染せずに作業が進むため、副作用のリスクを限定しながら自律実行を許可できる（出典: https://github.com/openai/codex/releases ）。

エージェントとして Codex を使う場合と、逐次的に指示を与えて使う場合とでは、期待するアウトプットの粒度が大きく異なる。後者は「この関数を修正して」という細かい指示を繰り返すスタイルだが、前者は「このモジュールのテストカバレッジを 80% 以上にしてほしい」という目標を渡して完了まで任せるスタイルだ。目標が曖昧だと Codex の判断がブレやすくなるため、「何を達成したか」で完了を判断できる形に言語化することが重要になる。

エージェント動作の特性を理解する

Codex が自律的に動くほど、想定外の変更が入るリスクも高まる。たとえば「API を改善して」という指示では、エージェントが不要な依存ライブラリを追加したり、既存のインターフェースを大きく書き換えたりする可能性がある。これを防ぐには、AGENTS.md に「既存の公開インターフェースは変更しない」「新しいライブラリの追加は禁止」といったガードレールを明記しておく方法が効果的だ。エージェントはこの制約を参照しながら判断するため、意図した範囲内での作業に収束しやすくなる。

エージェント実行の事前準備

AGENTS.md の作成

Codex はリポジトリのルートに AGENTS.md ファイルがあると、タスク実行前にこのファイルを読み込む。記述した内容がそのままエージェントの行動指針となるため、以下の4項目を最低限含めておくことが推奨される（出典: https://github.com/openai/codex/releases ）。

1. プロジェクトの概要（何を作っているか、使っている主要技術）
2. コーディング規約（言語バージョン、命名規則、テストフレームワーク）
3. 禁止操作（変更してはいけないファイル、実行してはいけないコマンド）
4. 完了の定義（テストが全部通る、型エラーがゼロ、など）

AGENTS.md の記述が詳細なほど、エージェントが途中で迷う回数が減り、トークン消費量も抑制できる。反対に、AGENTS.md なしで大規模タスクを渡すと、エージェントがコードベースの意図を独自に推測して動くことになり、実行結果の予測が難しくなる。

# プロジェクト概要
TypeScript + Node.js で書かれた REST API サーバー。

# 技術スタック
- Node.js 22 / TypeScript 5.4
- ORM: Prisma（PostgreSQL）
- テスト: Vitest

# コーディング規約
- 型推論が自明な箇所以外は型を明示する
- 非同期処理は async/await を使用する
- 関数は 50 行以内を目安にする

# 禁止操作
- .env ファイルの変更
- prisma/migrations/ 内のファイルの編集
- npm install による新規パッケージの追加

# 完了の定義
- `npm run test` がすべてパスする
- TypeScript の型エラーがゼロであること

このような AGENTS.md を用意しておくと、「認証ミドルウェアにレート制限を追加して」という指示に対してエージェントが無関係なファイルを触るリスクが大幅に減る。

サンドボックスモードの選択

Codex アプリには「ネットワークアクセス前に確認する（ask before networking）」モードと「ネットワークアクセスを許可する」モードがある。エージェントがウェブ検索や外部 API への接続を必要とする場合は後者を選ぶが、センシティブなコードベースや社内ネットワーク環境では前者を選んで都度確認する運用が安全だ。

v0.142.0 で追加されたインデックス付きウェブ検索は、エージェントがタスク実行中に公式ドキュメントや Stack Overflow を参照しながら処理を進める機能だ。ネットワークアクセスを許可しているときにこの機能が有効になり、特定ライブラリの最新 API を正確に把握した上で実装を行えるようになる（出典: https://github.com/openai/codex/releases ）。長時間の自律実行においては、エージェントが古い情報に基づいて誤った実装を行うリスクが下がるため、信頼性の向上に貢献する。

自律タスクの構造化と渡し方

Codex にエージェントとして動いてもらうとき、タスクの記述が曖昧だと実行結果が安定しない。「コードを改善してほしい」より「src/auth/ 配下の全関数にユニットテストを追加し、カバレッジを 80% 以上にしてほしい」のように、完了条件を測定可能な形で書くことが出発点になる。

タスクが大きすぎると、エージェントが中途半端な状態で打ち切りになるか、意図しない方向に走る可能性が高まる。目安として「一回の PR に収まる規模のタスク」が自律実行に適している。複数のモジュールをまたぐ大規模リファクタリングや、アーキテクチャの変更を含む作業は、先にタスクを分割してから順に渡す方が制御しやすい。

タスク粒度の設計

エージェントに渡すタスクを設計するときの判断軸は次のとおりだ。

自律実行に向いているタスク: テストの追加、リントエラーの一括修正、定型的なドキュメントコメントの生成、依存ライブラリのバージョン更新に伴う API 変更への対応。これらは「正しい状態」が一意に定まりやすく、エージェントが完了を自己判断しやすい。

段階的な指示が向いているタスク: 新機能の設計判断が必要な実装、セキュリティ要件が絡む認証フローの変更、複数システムをまたぐ統合テスト。これらは判断が分岐しやすく、都度ユーザーが確認に入る方が最終的な品質が上がりやすい。

エージェント実行の途中で Codex が「どちらの方針を取るか」という選択を迫ってくる場面がある。この問いかけを放置すると処理が止まるため、AGENTS.md にデフォルトの方針（「迷ったら保守的な選択をする」「不明な場合はコメントを残して次の処理に進む」など）を書いておくと、中断なく実行が続きやすくなる。

トークン予算とコスト管理

v0.142.0 のトークン予算追跡

v0.142.0 で追加されたトークン予算追跡機能は、Codex アプリの設定画面からタスクごとに消費上限を指定できる。上限に達するとエージェントは現在の状態をレポートして処理を停止するため、意図しない大量消費を防げる（出典: https://github.com/openai/codex/releases ）。

予算の設定値は、タスクの複雑さによって大きく変わる。単一ファイルへのテスト追加であれば数千トークンで完了するが、数十ファイルにわたるリファクタリングは数万トークンを消費することもある。初めてエージェントに任せるタスクは、まず低い予算で実行して途中経過を確認し、実際の消費量を把握してから上限を調整するアプローチが安全だ。

Codex の利用料金の詳細は公式の料金ページで確認できる（出典: https://openai.com/pricing ）。チームで Codex を利用する場合は、月次のクレジット配分計画を立て、エージェント実行の実績データを蓄積することで、各タスクにかかるコストの見通しが立てやすくなる。

実践的な活用パターン

バグ修正の自律実行

GitHub や Jira でバグチケットの詳細が整っている場合、そのチケットの説明文を Codex への指示として直接使える。「src/payment/ の calculateTax 関数が税率 10% の場合に端数処理を誤る。期待値は切り捨て、現在は四捨五入されている」のような記述であれば、エージェントが問題箇所を特定し、修正を加え、テストケースを追加するところまで自律的に進む。

修正後の diff をレビューする工数は残るが、「問題を再現するテストを書く→コードを修正する→テストを通す」という定型サイクルをエージェントが担うことで、開発者は本来のレビュー判断に集中できる。

リファクタリングへの応用

「Promise.all を使っていない連続する async 関数を並列化してほしい」「型 any を使っている箇所を適切な型に置き換えてほしい」といった、パターンが一定なリファクタリングはエージェントが得意とする領域だ。コードベース全体を走査して該当箇所を洗い出し、順次変更してテストを確認するという作業をまとめて任せられる。

ただし、ドメインロジックの意図が分からないとエージェントが判断できない箇所では処理が止まるか、意図と異なる変更が入ることがある。AGENTS.md に「判断できない場合は TODO: requires human review コメントを残して次の箇所に進む」と明記しておくと、エージェントが迷った場所が後で一覧できる形で残り、レビューしやすくなる。

調査+要約の組み合わせ

v0.142.0 のインデックス付きウェブ検索を使うと、エージェントが調査を伴うタスクにも対応できる。「このプロジェクトで使っている react-query v4 を TanStack Query v5 に移行するための変更点を調査し、マイグレーションガイドを Markdown にまとめて docs/migration-tanstack.md に出力してほしい」のような指示に対して、エージェントが公式ドキュメントを参照しながら現在のコードとの差分を整理したドキュメントを生成できる（出典: https://github.com/openai/codex/releases ）。

エージェント実行時の注意点

エージェントとして Codex を使う際に押さえておくべき点が3つある。

1. git のコミット状態を整えてから実行する: エージェントがファイルを変更する前に git status がクリーンな状態にしておくと、diff の確認が容易になる。中途半端な変更が混在している状態でエージェントを動かすと、どの変更がエージェントによるものかを後から判別しにくくなる。

2. 完了後は必ず diff をレビューする: Codex はテストが通ることを完了の判断基準にするが、テストでカバーされていない副作用まで完全に検知できるわけではない。エージェントが変更した範囲を git diff で確認し、意図しない変更が含まれていないかを確認してからコミットするプロセスを習慣にすることが重要だ。

3. 予算と時間の制限を活用する: 特に初めて試すタスクは、小さいトークン予算で実行して途中経過を確認する。エージェントが想定と異なる方向に進んでいることが途中で分かれば、早い段階で停止して指示を修正できる。大きい予算で一気に走らせると、誤った方向に大量のトークンを使った後で気づくことになる。

これらを踏まえた上で Codex エージェントを活用すると、テスト追加やリファクタリングといった定型的な作業の多くを委ねられるようになり、開発者は設計判断や難しい問題解決に時間を集中できる。エージェント機能の最新情報と変更履歴は、公式リポジトリのリリースノートで継続的に確認できる（出典: https://github.com/openai/codex/releases ）。