Codex完全ガイド｜依頼・AGENTS.md・権限・レビュー・検証を一から組み立てる

Codex（コーデックス）は、コードを調べて直し、テストして、レビューまで一続きで進められる道具です。とても便利ですが、依頼を一文送るだけで品質と安全が自動で守られるわけではありません。作業の範囲を狭くし、繰り返すルールを共有し、権限（=触ってよい場所）を最小限にし、結果を機械の証拠として残す。この四つが土台になります。

この記事は、初めての人が最初の依頼から公開直前まで迷わないように、Codexの使い方を一つの流れとしてまとめた総合ガイドです。むずかしい言葉は、そのつどカッコで言い換えを添えます。読み終えたら、あなたの手元のプロジェクトで、小さく安全に一歩を踏み出せる状態を目指します。

大事な前提を先に一つ。Codexの説明がもっともらしくても、実際のファイルやコマンドの結果と一致するとは限りません。「終わりました」の根拠は、会話の自信ではなく、変更したファイル・差分・テストの出力・まだ確かめていないこと、です。AIを判断者ひとりにせず、機械の検査と人の確認を必ず組み合わせます。

Codexの作業を一つの流れでとらえる

まず、全体の地図を持ちます。この記事では、Codexの仕事を「探索・計画・編集・検証・報告」の五段階として整理します。これはこのサイトが読者向けに考えた実務の並べ方であって、OpenAIが定めた固定の手順ではありません。どれか一つを飛ばすほど、速く見えても、あとで確認や直しが増えます。

段階	やること	Codexへ渡す情報	合格の証拠
探索	現状と制約を知る	作業フォルダ、読むべき設計	関連ファイルと既存の仕様
計画	変える範囲を固定する	目的、対象、やらないこと	短い手順と止める条件
編集	必要な差分だけ作る	既存の名前の付け方・書式	対象の中だけの差分
検証	動きと副作用を確かめる	正式なテストのコマンド	出力、終了コード（=成否の番号）
報告	次の判断を可能にする	報告の形	変更・検証・残ったリスク

最初から「コードを書いて」と頼むより、「まず構成を読み、変える候補と確かめ方を報告して。まだ編集しないで」と頼むほうが安全です。Codexが見ている範囲を先に確認できるからです。そのあと、小さな変更を一つだけ行い、差分とテストを受け取ります。WindowsでCLI（=文字で命令する黒い画面）から始めるなら、先にCodex CLIをWindowsで始める手順を通しておくと詰まりにくくなります。

なお、実装後に何を確かめるかは、感覚ではなく手順で決めます。OpenAI公式のBest practicesでは、むずかしい仕事は実装前に計画し、実装後はテストの作成・更新、適切なテスト一式、lint（=書き方の自動チェック）・整形・型検査、要求との一致、そして差分レビューまで確認する流れが案内されています。この記事の並べ方も、その考え方に沿っています。

最初の依頼とAGENTS.mdで土台を作る

良い依頼には、四つの要素があります。OpenAI公式のBest practicesは、依頼に「Goal（目的）」「Context（関係するファイルやエラー）」「Constraints（変えないこと）」「Done when（完了の条件）」を入れることをすすめています。長い背景を全部書く必要はありませんが、結果が分かれる情報は省きません。

要素	中身	書き方の例
Goal（目的）	何を達成したいか	お問い合わせフォームの二重送信を防ぐ
Context（文脈）	関係するファイル・エラー	src/components/ContactForm.tsx と対応テスト
Constraints（制約）	変えないこと	API仕様と依存パッケージは変えない。本番へ反映しない
Done when（完了条件）	どうなったら終わりか	送信中は再送できず、既存の成功・失敗の挙動を保ち、対象テストが通る

依頼文をそのまま使うなら、次の型が入口になります。

目的: お問い合わせフォームの二重送信を防ぐ。
文脈: src/components/ContactForm.tsx と対応テストだけ。
制約: API仕様と依存は変えない。本番へ反映しない。
完了条件: 送信中は再送できず、成功・失敗の既存挙動を保ち、対象テストが通る。
報告: 変更ファイル、実行コマンド、出力、未確認事項。

大きい・あいまい・後戻りが大きい仕事のときだけ、先に「まだ編集しない調査と計画」を頼みます。逆に、小さくて戻せる判断は完了条件の範囲でCodexに進めさせると、質問の往復を増やしすぎません。依頼には目的・文脈・制約・完了条件を入れ、テストを頼む場合も再現条件・期待結果・証拠の3点を同じ依頼へ入れます。

毎回おなじルールを依頼文へ貼っているなら、それはAGENTS.md（=繰り返すルールを置くファイル）へ移す合図です。公式のCustom instructions with AGENTS.mdによると、Codexは作業前にこの指示ファイルを読み、グローバル（全体）→プロジェクトの根っこ→いま作業している場所、の順に指示を結び付けます。作業場所に近い指示があとから入り、優先されます。同じ階層ではAGENTS.override.mdがAGENTS.mdより先に選ばれ、各フォルダでは一つのファイルだけが採用されます。

AGENTS.mdに向くのは、正式なビルド・テストのコマンド、名前の付け方、フォルダの役割、触らない場所、報告の形です。今回だけのチケット内容や締切は依頼文へ残します。

プロジェクト概要:
- src/ は製品コード、tests/ は自動テスト。

変更ルール:
- 依頼にない依存を追加しない。
- 既存の命名と整形ツールに従う。
- 秘密をコード・ログ・例へ書かない。

検証:
- 変更箇所に近いテストを先に実行する。
- 失敗した検証を成功と報告しない。

このファイルを百科事典にしないことも大切です。読み込みには上限があり、公式案内では合計の既定値が32 KiB（キビバイト＝約32,768バイト）とされています（2026年8月23日時点の公式案内。上限の値や設定名は変わることがあるので、必要なときに公式ページで確認してください）。長い背景や一部の担当だけに必要な手順は別資料へ分け、入口だけを置きます。詳しい配置と最小のひな形はAGENTS.mdの書き方にまとめています。

権限を分け、差分とレビューで守る

安全の仕組みは、二つの層に分けて考えます。公式のAgent approvals & securityによると、Codexには「サンドボックス（=技術的に触れてよい範囲）」と「承認ポリシー（=どの操作で人へ確認するか）」があり、この二つは別ものです。ローカル（=自分のパソコンの中）では、既定でネットワーク（=外部との通信）が無効で、書き込みはふつう、いま作業しているフォルダに限られます。

最初は、この狭い既定のまま使います。書き込み先が足りないときだけ、なぜ必要か・どのパスか・戻せるかを確認してから広げます。原因別の見方はCodexのsandboxエラーを解決するが詳しいです。ここで覚えておくのは、承認の確認を減らしても、サンドボックスの制限まで自動で消えるわけではない、という点です。

秘密情報（=APIキー、アクセストークン、秘密鍵、パスワード、個人情報を含む実データ）は、次の順で扱いを検討します。

1. 値そのものではなく、環境変数の名前だけで実装できないか。
2. ダミー値やテスト用の資格情報で再現できないか。
3. 読み取り専用・短い有効期限・対象を限った権限にできないか。
4. ログや差分に出ない方法になっているか。
5. もし漏れを疑ったときの、無効化・再発行の手順があるか。

秘密の扱いはAGENTS.mdに「本番を変えない」と書くこととは別の安全策です。指示ファイルは共有の仕組みであって、本番権限を技術的に止める壁ではありません。値を依頼文へ貼らず、環境変数名・ダミー値・短い有効期限・読み取り専用権限の順で被害範囲を小さくします。

実装が終わったら、まず「何をレビューするか」を差分で固定します。git-diff の公式ドキュメントによれば、git diffは未ステージ（=まだ記録待ちの変更）と手元の記録の差、git diff --cachedは記録待ちと直近コミットの差、git diff HEADは作業ツリーと直近コミットの差を示します。範囲を先に決めてからレビューすると、見落としが減ります。

レビューでは「どう作ったか」より「何が壊れる可能性があるか」を見ます。GitHubを使うなら、公式のCodex code review in GitHubにあるとおり、プルリクエスト（=変更の提案）で@codex reviewが使え、AGENTS.mdのCode Review Rulesで観点を調整できます。ただし公式は、このレビュー規則がテスト・ブランチ保護・必須承認の代わりにはならないと明記しています。指摘は重要度順に並べ、各項目に対象箇所・発生条件・影響・確認方法を添えます。

重要度	例	必要な情報
高	データ損失、認証回避、主要機能の停止	発生条件、影響範囲、再現の証拠
中	特定入力での誤動作、アクセシビリティ欠落	対象の利用者、期待する結果、修正案
低	読みやすさ、将来の保守の負担	具体的な改善理由

最後の合流（=マージ）は、別の工程にします。GitHub公式のPull request reviewsでは、レビューでComment・Approve・Request changesの三つの判断を返せて、管理者は重要なブランチでマージ前の承認を必須にできます。AIの指摘と人の承認を組み合わせ、直す型はCodexにコードレビューを任せる手順にまとめています。

テスト・機械証拠と、止まったときの立て直し

「テストもして」と頼むだけでは、何を実行したかがあいまいになります。正式なコマンドがあるならAGENTS.mdやREADMEで示し、変更に近い検証から広い検証へ順に進めます。

1. 変えたファイルの構文・整形・型検査。
2. 変えた機能の単体・結合テスト。
3. 関連する既存機能の回帰テスト（=前と同じ動きが壊れていないか）。
4. 必要に応じて全体ビルドや、実際の画面での確認。

記事サイトでこの順序を具体化する例は、Astro記事サイト運用完全ガイドで確認できます。原稿の型検査、ビルド、内部リンク検査、生成HTML確認を別の証拠として扱うため、Codexへ渡す完了条件の例にもなります。

JavaScriptのプロジェクトなら、npm-testが入口です。npm testはpackage.jsonのscripts.testに書いたコマンドを実行し、引数はnpm test -- <引数>の形で渡せます。報告には、コマンド・終了コード・主要な出力・実行できなかった項目を必ず入れます。成功の行だけ抜き出すと、警告や一部の失敗が隠れます。

会話の「終わりました」だけで合格にせず、機械の証拠でも確かめます。GitHub公式のStatus checksによると、ステータスチェック（=CIの自動検査結果）はビルドやテストの結果を示し、保護ブランチで必須にしたチェックはマージ前に通過が求められます。ただし、skipped（飛ばした）やneutral（中立）が成功として扱われる条件があるので、「緑なら全部のテストが走った」とは決めつけず、実行されたジョブとログも見ます。観点の定型化はAI生成コードの検品チェックリストへ進んでください。

Codexが途中で止まって見えるときは、原因を分けます。入力待ち、承認待ち、サンドボックスの外、ネットワーク無効、コマンド失敗、テスト失敗。最後の出力と終了コードを見ずに同じ依頼を繰り返すと、原因が残ったままになります。再試行する前に、対象を小さくする・公式仕様を確認する・失敗コマンドだけを再現する、のように条件を必ず一つ変えます。権限や安全機構を無効にして通すのは、原因の解決ではありません。

長い作業を続けるときは、履歴を丸ごと読ませるより、いまの正本と短い引き継ぎを残します。引き継ぎには、目的・確定したこと・変更ファイル・実行した検証と結果・残件・次の一手を書き、実行済みと未実行を分けます。「たぶん直った」「あと少し」だけでは、次の担当が同じ調査をやり直します。並列作業でも担当ファイルを重ねず、同じ形式の短い引き継ぎを残します。

よくある質問

AGENTS.mdは必ず作らないといけませんか？

必須ではありません。単発の小さな依頼なら、依頼文だけでも進められます。ただし、起動・テストのコマンドや禁止事項を毎回くり返すなら、AGENTS.mdへ移すと使い回しがきいて楽になります（公式のBest practicesとAGENTS.mdの案内より）。

複数のAGENTS.mdがあるとき、どれが使われますか？

グローバル→プロジェクトの根っこ→いまの作業フォルダ、の順に結び付けられ、作業場所に近いものがあとから入って優先されます。同じ階層ではAGENTS.override.mdがAGENTS.mdより先に選ばれます（公式のAGENTS.mdより）。

サンドボックスと承認は何が違いますか？

サンドボックスは「技術的に触れてよい範囲」、承認ポリシーは「どの操作で人へ確認するか」を決めます。承認の確認を減らしても、サンドボックスの制限まで自動で消えるわけではありません（公式のAgent approvals & securityより）。

Codexのレビューを実行すると、コードも自動で直りますか？

レビューと修正は分けて考えます。GitHubでは@codex reviewで指摘を受け、採用する指摘が決まってから修正を依頼します。書き込み権限がなければ、修正は反映できません（公式のCodex code review in GitHubより）。

テストが通れば、その変更は完成ですか？

テストの合格は大事な証拠ですが、それだけで要件どおりの動きやレビュー承認まで保証するわけではありません。要求どおりの挙動・差分レビュー・必要なステータスチェック・人の承認を組み合わせて判断します（GitHub公式のStatus checksとPull request reviewsより）。

まとめ

• まず小さく始める。「まだ編集しないで、構成を読んで変更候補と確かめ方を報告して」と頼み、そのあと一つだけ小さな変更を依頼して差分とテストを受け取ってください。
• 土台を分けて固める。くり返すルールはAGENTS.mdへ、秘密情報はサンドボックス・承認・ネットワークの制限へ、と役割ごとに置き場を分けてください。
• 完了は証拠で決める。会話の「終わりました」ではなく、git diffで範囲を固定し、テストの出力・終了コード・ステータスチェック・人の承認をそろえてから合流してください。設定名や既定値は変わりやすいので、公開や設定変更の直前に公式ページを再確認してください。

公式一次情報

著者・作成方法・確認日・広告開示: ユタラボ編集部が、OpenAI・GitHub・npm・Gitの公式資料を照合し、依頼から報告までを5段階の判断表へ整理して作成しました。主要仕様の確認日は2026-08-23です。本文内に広告・アフィリエイトリンクはありません。

確認日: 2026-08-23

• Best practices | ChatGPT Learn: 依頼にGoal・Context・Constraints・Done whenの4要素を入れ、実装後はテスト・整形・型検査・差分レビューまで確認する流れを案内。
• Custom instructions with AGENTS.md | ChatGPT Learn: AGENTS.md系の探索順、AGENTS.override.mdの優先、近い指示が優先されること、既定32 KiBの読込上限を説明。
• Agent approvals & security | ChatGPT Learn: サンドボックスと承認ポリシーの二層、既定でネットワーク無効・書込みは作業場所に限定される点を説明。
• Codex code review in GitHub | ChatGPT Learn: @codex reviewの手順とCode Review Rules、レビュー規則がテスト・ブランチ保護・必須承認の代わりにならない点を明記。
• Pull request reviews - GitHub Docs: レビューでComment・Approve・Request changesを返せること、マージ前の承認を必須にできることを説明。
• Status checks - GitHub Docs: ステータスチェックがビルド・テスト等の結果を示し、保護ブランチで必須にしたチェックはマージ前に通過が必要と説明。
• npm-test | npm Docs: npm testがpackage.jsonのscripts.testを実行し、引数は npm test — の形で渡せると説明。
• Git - git-diff Documentation: git diff・git diff —cached・git diff HEADがそれぞれ異なる範囲の差分を示すと説明。

CLIのコマンド名、画面名、設定キー、既定値、GitHub連携の対象範囲は更新されることがあります。設定を変えるときや公開の直前には、上記の公式ページをもう一度開いて確認してください。