Codex の AGENTS.md：置き場所、読み込み順、書く内容

Codex が AGENTS.md を探す場所（読み込み順）

Codex は起動時に一度だけ指示のチェーンを組み立てます（ターミナル UI ではセッションごとに一度）。ファイルはこの表の上から順に連結されるため、作業ディレクトリに近い指示ほど後に来て優先されます。

Codex 用に AGENTS.md を設定する方法

1. グローバルの既定を作る

   mkdir -p ~/.codex を実行し、すべてのリポジトリで使いたい設定を ~/.codex/AGENTS.md に書きます。Codex に指示の要約を頼んで、読み込まれたか確認しましょう。

   # ~/.codex/AGENTS.md
   
   ## Working agreements
   
   - Always run `npm test` after modifying JavaScript files.
   - Prefer `pnpm` when installing dependencies.
   - Ask for confirmation before adding new production dependencies.

2. プロジェクトのファイルを追加し、ルールが違う場所はオーバーライドする

   共通の設定はリポジトリのルートの AGENTS.md に書きます。ルールが異なるフォルダには AGENTS.override.md を追加します。これはそのフォルダの AGENTS.md を置き換え、Codex は元のファイルを無視します。

   # AGENTS.md (repository root)
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.
   
   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use `make test-payments` instead of `npm test`.
   - Never rotate API keys without notifying the security channel.

3. 読み込まれたものを確認する

   対象のフォルダで Codex を起動し（例：codex --cd services/payments）、読み込んだ指示の出典を一覧にするよう頼みます。グローバルファイル、ルートのファイル、そのフォルダのファイルの順に表示されるはずです。

4. 既存のファイル名を使う、または上限を上げる

   リポジトリがすでに別のファイルに指示を書いているなら、~/.codex/config.toml の project_doc_fallback_filenames に追加します。合計サイズが project_doc_max_bytes（既定は 32 KiB）に達すると、Codex はそれ以上ファイルを追加しません。

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

5. Codex のコードレビュー用ルールを追加する

   GitHub の @codex review 向けには、対象のコードに最も近い AGENTS.md に ## Code Review Rules セクションを追加します。指摘すべきことと安全な代替策を書き、フォーマットや lint は CI に任せましょう。

   ## Code Review Rules
   
   ### Experiment cohorts
   
   - Do not filter treatment comparisons on post-exposure behavior.
     Safe path: build cohorts from assignment or exposure.

出典：Codex ドキュメント、Custom instructions with AGENTS.md

AGENTS.md のベストプラクティス

• Codex が自分では把握できないことだけを書きます。正確なビルド・テスト・lint のコマンド（テストを1つだけ実行する方法も含む）、コードベースの落とし穴、どこにも書かれていない決定事項です。
• 最も具体的なルールはコードの近くに置きます。services/payments/ にネストした AGENTS.md のほうが、ルートの長いファイルにある決済のセクションより効果的です。
• 32 KiB の予算に注意しましょう。ファイルはルートから順に追加され、残りは切り捨てられるので、長いファイルはネストしたファイルに分けるか、project_doc_max_bytes を上げます。
• 一時的な変更にはグローバルでもフォルダ単位でも AGENTS.override.md を使い、削除すれば元に戻ります。
• 空の AGENTS.md はスキップされ、そのディレクトリでは次のファイル名の確認に進みます。
• 自動化用のユーザーには別の CODEX_HOME を使い、そのグローバル指示が自分のものと混ざらないようにします。

Codex と Claude Code などにおける AGENTS.md の違い

AGENTS.md は多くのエージェントが読むオープンな形式なので、共有したい指示を置くのに最適です。Claude Code には独自のファイル CLAUDE.md があります。詳しくは CLAUDE.md ガイドをご覧ください。

AGENTS.md は Codex にやり方を教え、Crewmark は次にやることを伝えます。

よい AGENTS.md があれば、どの Codex セッションも状況を把握した状態で始まりますが、セッションはあなたのプロンプトを待ったままです。Crewmark は Codex、Claude Code、DeepSeek Harness、OpenCode のセッションを、職種・目標・勤務時間を持つ AI 社員に変え、ハートビートで起こしてボードから次の issue を取らせます。

1. AGENTS.md はリポジトリに置いたままにする

   社員の Codex セッションもあなたのセッションと同じように読み込むので、規約やテストのコマンドもそのまま引き継がれます。

2. ハートビートで仕事を始めさせる

   勤務時間中、社員は15分、30分、60分ごとに同じ会話の中で起きます。詳しくはCodex を自律的に動かす方法をご覧ください。

3. 1つのボードでエージェントを混在させる

   1つの AGENTS.md で Codex と Claude Code の社員を並行して動かせます。違いは Claude Code と Codex の比較をご覧ください。

Codex AGENTS.md のよくある質問