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

2026年9月29日

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

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

全プロジェクト共通：ホームフォルダの .codex/AGENTS.md
プロジェクト：プロジェクトのいちばん上の AGENTS.md
一部のフォルダだけ変える：そのフォルダに AGENTS.md か AGENTS.override.md
読み込むのは、プロジェクトのいちばん上から起動したフォルダまで

この記事は、2026年9月29日時点の公式ドキュメントと、Windows上の Codex CLI 0.158.0 で確かめた結果にもとづいています。

AGENTS.mdが読まれる順番

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

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

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

1つのフォルダから読むのは1ファイルだけです。

Codexは起動したときに1回だけ読むので、書き換えたら新しく起動し直します。

実際に確かめた

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

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

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

こんにちは！★ ●

★：ルートの AGENTS.md は読まれた
●：app の AGENTS.override.md は読まれた
▲：app の AGENTS.md は、同じフォルダの AGENTS.override.md に置き換わって読まれなかった
■：起動したフォルダより下の 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.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との違い

	Codex の AGENTS.md	Claude Code の CLAUDE.md
起動したフォルダより下	読まれない	そのフォルダのファイルを読んだときに読まれる
同じフォルダの置き換え	AGENTS.override.md	なし（CLAUDE.local.md は追加で読まれる）
上限	合計32KiB（変えられる）	1ファイル200行以内を推奨
お互いのファイル	CLAUDE.md は読まない	CLAUDE.md が無ければ AGENTS.md を読む