Codex AGENTS.mdの書き方｜配置・優先順位・反映確認まで

Codexに毎回「このディレクトリは触らないで」「変更後はこのテストを実行して」と書いているなら、AGENTS.mdへ移すと指示を再利用できます。ただし、ルールを1枚に詰め込むだけでは安定しません。重要なのは、どの範囲に効かせるか、どの指示を優先させるか、実際に読み込まれたかを確認することです。この記事では、AGENTS.mdを「ルールの保管場所」ではなく「Codexの指示設計」として扱い、最小テンプレからモノレポ、反映確認まで順に整理します。

まず結論：AGENTS.mdは3層で置き場所を決める

CodexのAGENTS.mdは、書く内容より先に「どの範囲へ効かせるか」を決めると整理しやすくなります。実務では、個人共通・リポジトリ共通・特定ディレクトリという3層で考えると十分です。

置き場所	向いているルール	例
`~/.codex/AGENTS.md`	複数Repositoryで共通する個人ルール	回答言語、共通の作業姿勢、毎回守る確認事項
Repository rootの`AGENTS.md`	そのRepository全体の共通ルール	セットアップ、テスト、命名規則、変更禁止領域、完了条件
サブディレクトリの`AGENTS.md`	その領域だけの固有ルール	frontendだけのlint、APIだけのテスト、infra固有の禁止事項

OpenAIの現行ドキュメントでは、Codexはglobalの指示を読み、その後Project rootから現在の作業ディレクトリまで指示ファイルを探索します。作業場所に近いファイルほど後から結合されるため、より具体的な指示として扱われます。

CodexがAGENTS.mdを読む順番を理解する

「書いたのに効かない」を減らすには、探索順を押さえておく必要があります。globalでは`AGENTS.override.md`があればそちらを使い、なければ`AGENTS.md`を使います。Project側も各ディレクトリでoverride、通常のAGENTS.md、設定したfallback名の順に候補を確認し、1ディレクトリにつき最大1ファイルを採用します。

優先して確認されるもの	意味
`AGENTS.override.md`	同じディレクトリの通常AGENTS.mdより優先する一時的・限定的な指示
`AGENTS.md`	通常の継続ルール
`project_doc_fallback_filenames`に登録したファイル	既存Repositoryで別名の指示ファイルを使いたい場合の代替

また、読み込むProject指示の合計サイズは`project_doc_max_bytes`で制御され、現行ドキュメントでは既定値が32KiBです。長大な1枚へ何でも詰めるより、共通ルールは上位、領域固有ルールは下位へ分ける方が、重要な指示を残しやすくなります。

用語解説：AGENTS.override.md
同じディレクトリにある通常のAGENTS.mdより優先して使われる指示ファイルです。一時的な運用差分や、特定領域だけ通常ルールを置き換えたい場合に使います。

最初のAGENTS.mdは5種類のルールだけでよい

競合記事でよくある失敗は、READMEの内容や一般論まで含めて長いテンプレートを作ることです。最初は「Context・Commands・Conventions・Boundaries・Done」の5種類だけに絞ると、運用で必要な行だけを育てやすくなります。

# AGENTS.md

## Context
- このRepositoryは顧客向けWebアプリです。
- frontendは`apps/web`、APIは`apps/api`です。

## Commands
- 依存関係: `pnpm install`
- Lint: `pnpm lint`
- Test: `pnpm test`

## Conventions
- 既存の命名規則と周辺実装を優先する。
- 関係のないリファクタリングを混ぜない。

## Boundaries
- `.env*`と本番設定は変更しない。
- 新しいproduction dependencyは追加前に確認する。

## Definition of Done
- 変更箇所に関係するテストを実行する。
- 実行できない検証があれば理由を明記する。
- 最後に変更ファイルと検証結果を要約する。

OpenAIのベストプラクティスでも、Repository構成、実行方法、build・test・lint、開発規約、制約・禁止事項、完了条件、検証方法などがAGENTS.mdに向く内容として挙げられています。抽象的な「きれいなコードを書く」より、コマンド・パス・完了条件のように確認できるルールを優先します。

モノレポでは共通ルールと領域ルールを分離する

frontendとAPIでコマンドや規約が違うRepositoryでは、rootのAGENTS.mdへ全部を書くと、関係のない作業でも不要な指示を読ませることになります。共通事項だけrootへ置き、差分を各ディレクトリへ寄せます。

repo/
├─ AGENTS.md
├─ apps/
│  ├─ web/
│  │  ├─ AGENTS.md
│  │  └─ src/
│  └─ api/
│     ├─ AGENTS.md
│     └─ src/
└─ packages/
   └─ ui/

ファイル	書く内容の例
`repo/AGENTS.md`	Repository全体のセットアップ、共通の禁止事項、PR前の共通検証
`apps/web/AGENTS.md`	frontend固有のlint、UI規約、ブラウザテスト
`apps/api/AGENTS.md`	API固有のテスト、migration、認証やDB変更の注意

同じルールを各階層へコピーするより、「上位に共通、下位に差分」と決めた方が、更新漏れや矛盾を減らせます。Codexは現在の作業ディレクトリまでの指示を組み合わせるため、作業場所に必要な情報だけを近くへ置く設計が有効です。

AGENTS.md・Prompt・Skills・Rulesを使い分ける

すべての指示をAGENTS.mdへ入れる必要はありません。Codexには、目的の違う指示面があります。ここを分けるとAGENTS.mdの肥大化を防げます。

仕組み	向いているもの	例
Prompt	今回だけの具体的な依頼	このIssueだけ修正する、今回はファイルを変更しない
AGENTS.md	Repositoryで繰り返し守る作業ルール	テストコマンド、命名規則、禁止領域、完了条件
Skills	繰り返す専門ワークフロー	リリース手順、レビュー手順、専用スクリプトを伴う作業
Rules	コマンド実行に対する許可・確認・禁止の制御	特定コマンドをsandbox外で実行する前に確認する

たとえば「本番DBを変更しない」はAGENTS.mdへ注意事項として書けますが、強制的な実行制御が必要なら、文章だけに頼らず権限やRulesなどの制御面を使う方が適切です。逆に、今回だけの変更範囲や受け入れ条件はPromptへ置いた方が、永続ルールを汚しません。

（一回限りの依頼を具体化するプロンプト設計も確認したい場合については『GPT指示精度を上げる方法｜ChatGPTで使える指示テンプレ7選』をご参照ください）

書いたら必ず「読まれたか」を確認する

AGENTS.mdは、保存しただけで終わりにしない方が安全です。OpenAIの公式ドキュメントでは、現在の指示をCodexに要約させる確認方法が案内されています。

codex --ask-for-approval never "Summarize the current instructions."

サブディレクトリ固有の指示を確認したい場合は、対象ディレクトリを指定して、どの指示ファイルが有効かを表示させます。

codex --cd apps/api --ask-for-approval never \
  "Show which instruction files are active."

rootの共通ルールが含まれているか
対象ディレクトリの固有ルールが含まれているか
意図していない`AGENTS.override.md`が有効になっていないか
古い指示や矛盾したルールが残っていないか

AGENTS.mdを編集したのに現在のセッションへ反映されない場合は、Codexを再起動して新しいrunで確認します。現行ドキュメントでは、指示チェーンはrun開始時に構築されます。

AGENTS.mdが反映されないときの切り分け順

症状	先に確認すること	対処
何も読み込まれない	作業しているRepositoryとcurrent directory	`codex status`でworkspace rootを確認する
古いルールが出る	globalや上位階層の`AGENTS.override.md`	不要なoverrideを外すか、意図した内容へ更新する
サブディレクトリのルールが効かない	Codexを起動した場所	対象ディレクトリから起動するか`–cd`で確認する
後半のルールが見えない	指示ファイルの合計サイズ	32KiB上限を確認し、内容を分割・削減する
書いた直後だけ反映されない	同じrunを使い続けていないか	新しいrunまたはCodex再起動で指示チェーンを再構築する
読まれているのに守られない	指示が曖昧・検証不能ではないか	具体的なコマンド、禁止パス、完了条件へ書き換える