Codex│AGENTS.mdの書き方と読み込まれる場所｜AGENTS.override.mdとの違い

AGENTS.md は、Codexが作業を始める前に読む指示書です。

テストの実行方法やコードの書き方など、毎回伝えたいことを書いておきます。

• 全プロジェクト共通：ホームフォルダの .codex/AGENTS.md
• プロジェクト：プロジェクトのいちばん上の AGENTS.md
• 一部のフォルダだけ変える：そのフォルダに AGENTS.md か AGENTS.override.md
• 起動時の自動探索は、プロジェクトのいちばん上から作業フォルダまで

2026年10月23日に公式の探索条件を再照合しました。実行結果は2026年9月29日のWindows版CLI 0.158.0の記録で、掲載画像は10月17日の再作成時のものです。今回、読込み順序の実機再検証はしていません。

AGENTS.mdが読まれる順番

1. ホームフォルダの .codex にある AGENTS.override.md、なければ AGENTS.md
2. プロジェクトのいちばん上（ふつうはGitのルート）から、起動したフォルダまでの各フォルダの AGENTS.override.md、なければ AGENTS.md

見つかったファイルは、上から順につなげて読まれます。

起動したフォルダに近いものほど後ろに来るので、そちらの指示が優先されます。

起動時に各フォルダから採用するのは最大1ファイルです。空ファイルは飛ばします。CODEX_HOMEを指定した場合、共通指示の置き場所も変わります。プロジェクトルートが見つからなければ、プロジェクト側は作業フォルダだけを調べます。

起動時の指示の組立ては実行ごとに行われます。変更した指示を確実に初期読込みへ反映するには、対象フォルダで新しい実行・セッションを開始してください。

CLI 0.158.0での確認記録

練習用のフォルダに、次のように置きました。

codex-agents/            ← Gitのルート
├── AGENTS.md            … 返事に「★」を含める
└── app/
    ├── AGENTS.md        … 返事に「▲」を含める
    ├── AGENTS.override.md … 返事に「●」を含める
    └── src/
        └── AGENTS.md    … 返事に「■」を含める

画像は、2026年10月17日にこの構成を練習用に作り直し、app フォルダをエクスプローラーで開いたところです。

app フォルダには AGENTS.md と AGENTS.override.md が同じ場所に並び、その下に src フォルダがあります。

4つのファイルの中身を、Windows PowerShell の Get-Content で表示しました。

ファイルごとに違う印を返すよう、1行ずつ書いています。

このときはファイルを作って画面を撮っただけで、Codex は起動しておらず、読み込まれる順番は確かめ直していません。

この PC の Codex CLI は codex --version で 0.160.0 と表示されましたが、下の結果は記事の執筆時に 0.158.0 で試したときのものです。

app フォルダで codex exec を実行し、指示ファイルのルールを守って挨拶してもらった結果です。

こんにちは！★ ●

• ★：ルートに書いた印が返答に現れた
• ●：appのoverrideに書いた印が返答に現れた
• ▲：返答には現れなかった。公式の探索規則では、同じフォルダの非空のoverrideが優先される
• ■：返答には現れなかった。srcは起動時の自動探索範囲外

作業フォルダより下のAGENTS.mdは、起動時に自動探索されません。作業中にツールでそのファイルを読むこととは区別してください。

サブフォルダのルールを効かせたいときは、そのフォルダで起動するか、--cd でそのフォルダを指定します。

codex --cd app/src

同じ結果を狙う指示はぶつかる

最初は、どのファイルにも「返事の最後に（名前）と書く」と書いて試しました。

このときは「(override)」だけが付き、ルートのものは付きませんでした。

同じことを別々に指示すると、後ろにあるものが優先されるためです。

上の階層と下の階層で同じことを決めるときは、下の階層の指示で上書きされるつもりで書きます。

AGENTS.override.mdの使いどころ

AGENTS.override.md は、同じ場所の AGENTS.md の代わりに読まれるファイルです。

• ホームフォルダ：共通の AGENTS.md を消さずに、一時的に別の指示で動かしたいとき
• サブフォルダ：そのフォルダだけ、まったく違うルールにしたいとき（例：決済のサービスだけテストのコマンドが違う）

override を消せば、元の AGENTS.md に戻ります。

書き方の例

# AGENTS.md

## 作業の決まり

- JavaScriptを直したら npm test を実行する
- 依存を入れるときは pnpm を使う
- 本番用の依存を足す前に確認する

GitHubのプルリクエストを Codex にレビューさせる場合は、## Code Review Rules という見出しの下に、見てほしい点を書けます。

32KiBの上限とほかの名前のファイル

読み込む量には上限があり、初期値は合計32KiBです。

上限に届くと、それより後のファイルは読まれません。

同じ探索経路のファイルを分割するだけでは合計は減りません。不要な記述を削る、対象別のフォルダへ整理する、またはconfig.tomlのproject_doc_max_bytesを調整してください。

すでに別の名前の指示ファイル（例：TEAM_GUIDE.md）があるなら、config.toml に次のように書くと、AGENTS.override.md・AGENTS.mdから採用される非空ファイルが無いフォルダで、指定名を順に試します。

project_doc_fallback_filenames = ["TEAM_GUIDE.md"]

config.toml の場所と書き方は、Codexのconfig.tomlの場所と書き方で紹介しています。

読み込まれたかを確かめる

公式ドキュメントでは、次のように読み込んだ指示を答えさせる方法が紹介されています。

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

ファイルごとの印は指示が返答に反映されたかを見る補助です。印がないだけでは、未読と指示不遵守を区別できません。読み込んだファイル名や、必要なら公式手順で有効にしたログも照合してください。

Claude CodeのCLAUDE.mdとの違い

この既定の判定では、ユーザー用の ~/.claude/CLAUDE.md、組織の管理用 CLAUDE.md、.claude/rules/ は対象外です。

AGENTS.md の直接読込は v2.1.277 以降の対応環境が対象で、古い版や組込プラグインを無効にした場合などの例外は、公式の読込条件を確認してください（2026年10月23日再照合）。

両方を使うなら、同じフォルダのCLAUDE.mdに@AGENTS.mdを引用符やコードブロックで囲まずに書くと、そのAGENTS.mdを取り込めます。

ただし、Claude CodeはAGENTS.override.mdを直接の探索対象にしないため、Codex側のoverrideまで同じように共有されるわけではありません。

Claude Code側の詳しい動きは、Claude CodeのCLAUDE.mdの書き方と置き場所で紹介しています。

まとめ

• ホームの .codex/AGENTS.md と、プロジェクトの上から起動したフォルダまでの AGENTS.md が読まれる
• 起動時には、作業フォルダより下を自動探索しない
• 同じフォルダに AGENTS.override.md があると、AGENTS.md の代わりに読まれる
• 合計32KiBを超えた分は読まれない

参考：公式Custom instructions with AGENTS.md（2026年10月23日照合）。

よくある質問：CodexのAGENTS.md

Codexの AGENTS.md は、どこにあるものが読まれますか？

ホームフォルダの .codex にある AGENTS.override.md（なければ AGENTS.md）と、プロジェクトのいちばん上（ふつうはGitのルート）から起動したフォルダまでの、各フォルダの AGENTS.override.md（なければ AGENTS.md）です。

見つかったファイルは、上から順につなげて読まれます。

起動時に各フォルダから採用するのは最大1ファイルです。空ファイルは飛ばします。CODEX_HOMEを指定した場合、共通指示の置き場所も変わります。プロジェクトルートが見つからなければ、プロジェクト側は作業フォルダだけを調べます。

複数のファイルで指示がぶつかったら、どちらが優先されますか？

起動したフォルダに近いものほど後ろに来るので、そちらの指示が優先されます。

記事の確認では、どのファイルにも「返事の最後に（名前）と書く」と書いたところ、「(override)」だけが付き、ルートのものは付きませんでした。

上の階層と下の階層で同じことを決めるときは、下の階層の指示で上書きされるつもりで書きます。

起動したフォルダより下のフォルダの AGENTS.md は、読まれますか？

起動時の自動探索には含まれません。作業中のツールによる読込みまで禁止されるわけではありません。

サブフォルダのルールを効かせたいときは、そのフォルダで起動するか、--cd でそのフォルダを指定します。

AGENTS.override.md は、どんなときに使いますか？

同じ場所の AGENTS.md の代わりに読まれるファイルです。

ホームフォルダでは、共通の AGENTS.md を消さずに一時的に別の指示で動かしたいとき、サブフォルダでは、そのフォルダだけまったく違うルールにしたいときに使います。

override を消せば、元の AGENTS.md に戻ります。

AGENTS.md を書き換えたら、すぐ反映されますか？

起動時の指示の組立ては実行ごとに行われます。変更した指示を確実に初期読込みへ反映するには、対象フォルダで新しい実行・セッションを開始してください。

読み込む量に、上限はありますか？

初期値は合計32KiBで、上限に届くと、それより後のファイルは読まれません。

同じ探索経路のファイルを分割するだけでは合計は減りません。不要な記述を削る、対象別のフォルダへ整理する、またはconfig.tomlのproject_doc_max_bytesを調整してください。

すでに別の名前の指示ファイル（例：TEAM_GUIDE.md）があるなら、config.toml に設定すると、AGENTS.override.md・AGENTS.mdから採用される非空ファイルが無いフォルダで、指定名を順に試します。

読み込まれたかどうかを、確かめるには？

公式ドキュメントでは、読み込んだ指示を答えさせる方法が紹介されています。

印の有無は返答への反映を確かめる補助です。読込みの証明にはならないため、ファイルの配置・有効な設定・必要に応じてログを照合してください。

Claude Codeの CLAUDE.md とは、どう違いますか？

Codexの AGENTS.md は、起動時には作業フォルダより下を自動探索せず、上限は合計32KiB（変えられる）で、同じフォルダの置き換えには AGENTS.override.md を使います。

Claude Codeでは、作業フォルダより下のCLAUDE.mdは、そのサブフォルダ内の別ファイルを読み取り・書込み・編集したときに読み込まれます。

1ファイル200行以内が推奨され、CLAUDE.local.mdはCLAUDE.mdに追加して読み込まれます。

Claude Codeは、既定では作業フォルダ・上位階層に CLAUDE.md／.claude/CLAUDE.md／CLAUDE.local.md が無ければ AGENTS.md を読みます（v2.1.277 以降の対応環境が対象で、例外は公式の読込条件を確認してください）。

両方を使うなら、同じフォルダのCLAUDE.mdに@AGENTS.mdを引用符やコードブロックで囲まずに書くと、そのAGENTS.mdを取り込めます。

実行例は2026年9月29日のCLI 0.158.0の記録です。今回の更新は公式資料との照合で、画面や実行結果の再現確認ではありません。

最新は公式ページで確認してください。