CodexでAI駆動開発を始める手順｜AGENTS.md・権限・レビューの実務

Codexはリポジトリを読み、ファイルを編集し、テストを実行しながら開発作業を進められます。ただし、対象が広いほど成果が大きくなるわけではありません。初回は、文言修正、既知の不具合、既存仕様に沿ったテスト追加など、期待結果を人が説明できる仕事を選びます。

避けたいのは、要件が決まっていない新機能、戻しにくいデータ変更、認証や決済の大幅な改修です。判断材料が足りない仕事を渡すと、Codexの能力よりも、要件の空白をどれだけ推測したかを評価することになります。AI駆動開発の全体像で工程を整理したうえで、その中の一工程だけを試すと切り分けやすくなります。

任せる仕事を決めたら、対象リポジトリを開き、作業前の変更が残っていないか確認します。以下は、既存の問い合わせフォームの二重送信を防ぐ場合の依頼例です。実際のファイル名やテストコマンドは、使っているプロジェクトに合わせて置き換えます。

最初は「問い合わせフォームの送信処理と既存テストを調べてください。まだ編集せず、二重送信が起こる条件、変更候補のファイル、確認すべきテストを挙げてください」と依頼します。回答では、実在するファイルと処理を根拠にしているかを確かめます。原因が特定できなければ、再現操作やログを補ってから進めます。

方針を確認したら「送信中の再送信を防ぐ最小限の修正をしてください。APIの形式と画面の他の挙動は変えず、必要な回帰テストを追加してください。変更理由、実行したテスト、その結果、未確認事項を報告してください」と依頼します。テストが成功したという説明だけで終えず、変更差分と実際の実行結果を確認します。未実行のテストがあれば、理由と代わりに確認できた範囲を残します。

OpenAIのCodexベストプラクティスも、必要な背景と完了条件を渡し、作業結果を検証する進め方を案内しています。この例をチームで使う際は、レビュー担当が次の条件を確認してから通常のPR手順へ進めます。

OpenAIのCodexベストプラクティスは、依頼にGoal、Context、Constraints、Done whenを含めるよう案内しています。日本語にすると、目的、背景、制約、完了条件です。長い文章を書くことが目的ではありません。何を変え、何を守り、どの証拠がそろえば終わりかを、レビューできる形で渡します。

たとえば「問い合わせフォームを直す」だけでは、対象も合格条件も分かりません。「二重送信を防ぐ。既存APIのリクエスト形式は変えない。送信中はボタンを無効化し、既存テストと追加した回帰テストが通ること」のように書けば、差分が意図を満たしたか判断できます。実装方法まで固定せず、守る契約と検証方法を先に固定します。

毎回の依頼に同じテストコマンドや禁止事項を書くなら、リポジトリ内のAGENTS.mdへ移します。OpenAIの公式資料では、Codexはグローバル、リポジトリ、下位ディレクトリの順に指示を探し、作業場所に近い指示を優先します。全体規約と、バックエンドやフロントエンドだけの規約を分けられる仕組みです。

AGENTS.mdは、その日のタスクを長く書く場所ではありません。ビルドとテスト、ディレクトリの責任範囲、生成物の扱い、禁止する操作、レビュー条件など、次の作業でも変わりにくい内容に絞ります。個別の目的と完了条件は依頼側へ残します。規約とタスクを分けると、Codexが参照すべき前提を更新しやすくなります。

Codexの安全設計では、ファイルやネットワークへ触れられる範囲と、その範囲を超えるときに人へ承認を求める方針を分けて考えます。OpenAIの公式資料も、サンドボックスと承認方針を別の制御として説明しています。両方を曖昧にすると、必要な作業が止まり続けるか、広すぎる権限を常用するかの二択になりがちです。

試行では、対象リポジトリ内の読み取りと編集、必要なテスト実行から始めます。外部ネットワーク、パッケージ追加、秘密情報へのアクセス、デプロイ、データ削除は、作業ごとに必要性を確認します。承認画面は安全の保証ではありません。何を実行し、どの範囲へ影響するかを人が判断できる情報がそろっていることが前提です。

設定値と作業別の判断順は、Codexのサンドボックスと承認の設計で具体的に整理しています。

常に制限を外す運用は避けます。承認が多すぎる場合は、AIを全面許可する前に、仕事の切り方が大きすぎないか、読み取りと書き込みを分けられないか、繰り返し許可できる安全なコマンドかを見直します。

難しい変更では、いきなり編集を始めず、関連コード、既存規約、変更候補、検証方法を先にまとめてもらいます。計画を人が確認したあとで実装へ進むと、要件の誤解を大量の差分にしてから見つける事態を減らせます。

実装後は、変更ファイル、意図、テスト結果、未確認事項をそろえます。Codexのコードレビュー機能は、未コミット差分、基準ブランチとの差分、特定コミットなどを対象に、問題点を指摘できます。実装を頼んだ会話の自己評価だけで終わらせず、差分をレビュー対象として切り出すことが重要です。

レビューで問題が見つかったら、指摘を直すだけでなく、同じ誤りが次回も起きる理由を見ます。恒久的な規約ならAGENTS.mdへ、テストで防げるなら回帰テストへ、要件の不足なら依頼テンプレートへ戻します。ブランチ保護や必須チェックまで含めた出口は、AI駆動開発のワークフローで詳しく整理しています。

試行の目的は、Codexを使った回数を増やすことではありません。選んだ1業務が、品質を保ったままレビュー完了まで進むかを確かめることです。着手からレビュー完了までの時間、レビュー往復数、CI失敗、手戻り、承認回数を、Codexを使わない同種作業と比べます。

速く差分ができても、レビューで作り直していれば工程全体は短くなりません。一方、実装時間が同じでも、既存仕様の調査やテスト観点がそろい、レビューの確認負荷が下がるなら導入価値があります。数値と一緒に、止まった理由を短く記録してください。指示不足、権限不足、テスト不足、ツールの不具合を分けないと、次の改善先が見えません。

2週間で見るのは、全社導入の可否ではありません。対象業務について、誰が依頼しても同じ規約を読み、必要な承認を通り、差分とテスト結果をレビューへ出せるかを確認します。再現できたら、隣の業務へ一つずつ広げます。

CodexとClaude Codeのどちらを標準にするかは、この運用を同じ条件で試したあとに判断できます。Claude CodeとCodexの比較でも、機能表だけでなく、差分品質、テスト、権限、レビュー負荷で比べる考え方を整理しています。

CodexでAI駆動開発を始める最小単位は、アカウント数ではなく、任せる仕事、指示、権限、検証がつながった一つの流れです。この流れを再現できれば、ツールの更新があっても、何を守って運用を変えるべきか判断できます。