Codex 向け AGENTS.md 完全設定ガイド（2026年版）
AGENTS.md は Codex（OpenAI Codex CLI）の永続的な指示ファイルで、リポジトリで作業を始める前に自動的に読み込まれます。Codex はこれを固定された検索順序（グローバル、次に git-root から現在のディレクトリまで）で探し、見つけたものをすべて連結し、結合後のサイズを 32 KiB で上限にします。これを超えた分は、警告もなく黙って捨てられます。ひとつ覚えておきたいのは、Codex は CLAUDE.md を読まないという点です。このガイドでは、その仕組み（検索順序、ファイルの結合方法、サイズ上限、そしてそのままコピーできる実際の AGENTS.md）を解説します。
- Codex の AGENTS.md まわりの仕様は変化が速く、以下の詳細は執筆時点（2026年8月）の公式ドキュメントと照合しています。実際に依存する前に、最新のドキュメントを確認してください。
Codex における AGENTS.md の役割（そして CLAUDE.md の話）
AGENTS.md は、セッションを開くたびに Codex がコンテキストへ読み込む永続的な指示ファイルです。プロジェクトの規約、テスト／ビルドのコマンド、破ってはいけないルールなどをここに書いておけば、毎回のプロンプトで繰り返す必要がなくなります。公式の learn.chatgpt.com/codex/agent-configuration/agents-md ドキュメントによると、Codex は固定された仕組みで AGENTS.md ファイルを見つけて読み込みますが、そのページには CLAUDE.md への言及は一度もありません。率直に言うと、現時点で Codex は CLAUDE.md を読みません。CLAUDE.md と AGENTS.md はまったく同じ発想のものであるにもかかわらず、です。
混同を避けるためにひと言：AGENTS.md（Codex の設定ファイル）は、AgentKit（Codex／Claude Code の中で動くキット、agentkit.best）とも、OpenAI AgentKit（OpenAI の Agent Builder／ChatKit）とも別物です。
Claude Code も併用していて、長いコンテキストファイルが本当に役立つのか知りたい場合は、AGENTS.md vs CLAUDE.md — そして長いファイルは本当に効果があるのかを参照してください。あちらの記事はその研究を扱っています。この記事はCodex 自身の設定の仕組みについてのものです。
Codex が AGENTS.md を探す場所 — 正確な検索順序
Codex は単一の AGENTS.md ファイルを読むのではなく、次の正確な順序で複数の階層をたどります（公式ドキュメントより）：
- グローバル階層：Codex はまず
~/.codex/AGENTS.override.mdを確認します。存在すれば、~/.codex/AGENTS.mdの代わりにそれを使います。オーバーライドがなければ~/.codex/AGENTS.mdを読みます。 - ディレクトリ階層（git-root から現在のディレクトリまでたどる）：Codex は git リポジトリのルートを見つけ、そこから
cwd（Codex を実行している場所）まで各ディレクトリ階層を下っていきます。どの階層でも同じオーバーライドのルールが適用され、その階層にAGENTS.override.mdがあればそれが優先され、なければAGENTS.mdが使われます。
例：あなたが ~/projects/shop/apps/web にいて、git ルートが ~/projects/shop だとします。Codex は次の順で確認します：グローバル（~/.codex/）→ ~/projects/shop/AGENTS.md（git-root）→ ~/projects/shop/apps/AGENTS.md（存在すれば）→ ~/projects/shop/apps/web/AGENTS.md（cwd）。存在しないものは単にスキップされ、エラーにはなりません。
オーバーライドファイルが実際に役立つ場面：チーム全体で共有する AGENTS.md を git にコミットしておきつつ、個人やマシン固有の調整を同じ階層の .override.md に入れておく、という使い方です。みんなが共有するファイルには手を触れずに済みます。
覚えておきたいのは、これは「最も近いファイルが勝ち、残りは無視される」ではないという点です。見つかったファイルはすべてまとめて結合され（次のセクション）、ひとつだけが選ばれるわけではありません。
ファイルはどう結合されるか — ルートから下への連結、近いファイルが勝つ
Codex はファイルを見つけると、そのうちひとつを選ぶのではなく、見つけたものをすべてひとつのコンテキストブロックに連結します。順序は検索と同じで、まずグローバル、次に git-root、そして各サブディレクトリ、という順に空行で区切られます。cwd に近いファイルほど最後に追加されるため、コンテキストの末尾に置かれます。そして 2 つの指示が衝突したときは、あとに現れる（cwd に近い）方が、通常はエージェントが従う指示になります。
3 つのファイルの例と、衝突したときにどれが勝つか：
~/.codex/AGENTS.md（グローバル）：「コミット前に必ず全テストスイートを実行すること。」~/projects/shop/AGENTS.md（git-root）：「npm ではなく pnpm を使うこと。」~/projects/shop/apps/web/AGENTS.md（cwd）：「このディレクトリを編集するときはユニットテスト（pnpm test:unit）だけを実行すること。全スイートは反復作業には遅すぎる。」
この 3 つは完全に矛盾しているわけではありませんが、ルール 3 はルール 1 と本当に衝突しています。ルール 3 は最後に追加されるため、Codex は apps/web の中で作業しているあいだはそれに従いがちです。だからこそ、あなたに最も近いファイルには具体的でローカルな指示を持たせ、グローバル／ルートのファイルには広く安定した規約だけを置くべきなのです。実際的には、これはサブディレクトリの AGENTS.md がグローバルのルールを完全に「無効化」できないことも意味します。できるのは、あとに続くより具体的な指示を追加することだけで、そのコンテキストではエージェントがそちらをより重視しがちになる、というだけです。
32 KiB の上限 — project_doc_max_bytes
見つかったすべての AGENTS.md ファイルの結合後のサイズ（各ファイル個別ではありません）は project_doc_max_bytes によって上限が定められ、既定は 32 KiB です。config-advanced ドキュメントによると、Codex は空のファイルをスキップし、結合後のサイズが上限に達した瞬間にコンテンツの追加を停止します。そこから先はコンテキストに一切入らず、TUI にエラーも警告も表示されません。
上限を引き上げるには、~/.codex/config.toml に次を追加します：
project_doc_max_bytes = 65536（65536 バイト = 64 KiB はあくまで一例です。実際に必要な値に設定してください。「念のため」で大きくしないこと。ファイルが長いほど、エージェントは一行一行に過剰反応しがちになります。下のシンプルな例を参照してください。）
| 設定項目 | 値 |
|---|---|
| 既定値 | 32 KiB（すべての AGENTS.md ファイルの合計に適用） |
| 設定方法 | ~/.codex/config.toml 内の project_doc_max_bytes |
| 上限を超えた場合 | コンテンツの追加を停止 — エラーも警告もなし |
| 空のファイル | スキップされ、合計にカウントされない |
黙って切り詰められる落とし穴（実際のバグ報告）
ここは他の多くのガイドが飛ばす部分です。GitHub Issue #7138（2025年11月22日に起票、「not planned（対応予定なし）」としてクローズ）は、まさにこれを記録しています。あるユーザーの結合後の AGENTS.md はおよそ 40 KB に達し、Codex はそれを黙って 32 KB に切り詰めました。TUI にも /stats にも警告はありません。この Issue は、コンテキストファイルが予算を超えたときに警告する Claude Code と、この点を明確に対比しています。
注：執筆時点で、この Issue は「not planned」としてクローズされています。つまり Codex チームには警告を追加する予定がありません。引用する前に Issue の最新ステータスを確認してください。トラッカーの状態は変わります。
実際的な対処法：あらゆる規約を巨大なひとつのルート AGENTS.md に詰め込まないことです。ディレクトリごとに分割し、グローバルのファイルは広い規約のために残し、各サブディレクトリにはそこに関係するものだけを持たせます。これにより 32 KiB の上限内に収まり、AGENTS.md／CLAUDE.md の研究がすでに見出したこと、つまり「長いファイルは役に立たず、コストが増えるだけ」という結論とも合致します。
project_doc_fallback_filenames と CODEX_HOME
深くカスタマイズするなら知っておきたい、2 つの小さめの設定：
project_doc_fallback_filenames：ある階層に AGENTS.md が存在しないときに、Codex がその階層で受け入れる代替ファイル名の配列です。チームがすでにTEAM_GUIDE.mdを使っていて、まだリネームする準備ができていない場合に便利です。~/.codex/config.tomlに設定します：project_doc_fallback_filenames = ["TEAM_GUIDE.md"]。CODEX_HOME：Codex の設定ディレクトリを指す環境変数で、既定は~/.codexです。ここにはconfig.toml、auth.json、history.jsonlが入っています。プロファイルやマシンごとに Codex の設定を分けたいときは変更します（たとえば CI ランナーごとに別々のCODEX_HOMEを用意し、自動セッションが個人のauth.jsonに触れないようにする、など）。
そのまま使える、実際のシンプルな AGENTS.md
以下は、私が Node／TypeScript のリポジトリで実際に使っているルート AGENTS.md です。あえて短くしています。長いファイルにしても Codex の性能は上がらないからです（上の落とし穴とコンテキストファイルの研究を参照）：
# Build & test
- Install: `pnpm install`
- Unit tests: `pnpm test` - e2e: `pnpm test:e2e` (Playwright, slow, run only when needed)
- Build: `pnpm build`
- Before committing: `pnpm lint && pnpm typecheck`
# Must not break
- Don't change the public API in `src/sdk/` without a major version bump.
- Never commit `.env*` files.
- Don't touch `infra/` (Terraform) outside a reviewed PR.
# Key paths
- API routes: `src/api/`
- Shared types: `src/types/`
- DB migrations: `db/migrations/` (never edit an applied migration, always add a new one)15 行です。「プロジェクト概要」も説明的な文章もありません。どの行も、実行できるコマンドか、具体的な「破ってはいけない」ルールのどちらかです。まさに AGENTS.md vs CLAUDE.md の研究が、エージェントが実際に行動に移す部分だと見出したところです。
AGENTS.md がルールを決め、AgentKit がスキルを足す
AGENTS.md は Codex がネイティブに読む無料の設定で、インストールするものは何もありません。これは「何をするか／何をしないか」に答えます。持ってこないのはパッケージ化されたスキルやワークフローで、それを足すのが AgentKit（agentkit.best、ak CLI）です。AgentKit は AGENTS.md を置き換えるのではなく、Codex の上で動きます。
Codex 向けにキットをインストールするには：ak kit init engineer --target codex --global（すべてのリポジトリで使うには --global を付けます）。その後、新しい Codex セッションの中で $ak:cook ... を実行します（Codex では $ak: 構文である点に注意。Claude Code の /ak: とは異なります。Codex での提供は現時点でネイティブのみ、すなわちスキル、ルール、エージェントのディスパッチ、一部のフックです。キットのコマンドはまだ有効ではなく、ステータスラインもありません）。
無料／有料の線引きをはっきりさせておくと：AGENTS.md は無料です。AgentKit は有料のアドオンです（Engineer Kit はおよそ $99、ストアではしばしば -20% で執筆時点でおよそ $79.20 まで下がります。最新の価格を確認してください）。Codex が初めてですか？まずは OpenAI Codex とは何かを参照してください。SKILL.md が実際に何なのか（AGENTS.md とは別物で、常に読み込まれるコンテキストではなくオンデマンドの機能です）知りたい場合は Codex Skills 解説を、Codex の中で AgentKit を動かす手順が知りたい場合は AgentKit in Codexを参照してください。
シンプルな AGENTS.md の上で、パッケージ化されたスキルを動かしたいですか？ AgentKit Engineer Kit は Codex と Claude Code のために事前構築されたワークフロー／スキルを追加します。基本的なルール設定の仕事は、引き続きあなたの AGENTS.md が担います。
よくある質問（FAQ）
Codex は CLAUDE.md を読みますか？
いいえ。公式ドキュメントによると、Codex は AGENTS.md（および AGENTS.override.md）ファイルだけを検索して読み込み、CLAUDE.md を読む仕組みはありません。同じリポジトリで Claude Code と Codex の両方を使う場合は、両方のファイルを残しておく（またはどちらか一方をもう一方にシンボリックリンクする）とよいでしょう。
Codex での AGENTS.md のサイズ上限は？
既定で 32 KiB です。見つかったすべての AGENTS.md ファイルの合計（各ファイル個別ではありません）に対して、project_doc_max_bytes 経由で適用されます。上限を超えた分は黙って捨てられ、エラーも警告もありません。~/.codex/config.toml で上限を引き上げられます。
グローバル、リポジトリルート、サブディレクトリの AGENTS.md がある場合、どれが勝ちますか？
どれかひとつが一方的に「勝つ」わけではありません。Codex はそれらをすべて、グローバルから git-root、そして現在のディレクトリへと下る順で結合します。現在のディレクトリに最も近いファイルが最後に追加されるため、何かが衝突したときには通常そのファイルの指示が採用されます。
AGENTS.override.md は何のためのものですか？
ある階層（グローバルまたはディレクトリ）に存在する場合、AGENTS.override.md はその同じ階層の AGENTS.md の代わりに使われます。チームで共有する AGENTS.md を git に置いたまま、共有ファイルに手を触れずに個人的なオーバーライドを追加するのに便利です。
ファイルが長すぎる場合、Codex は警告してくれますか？
いいえ、少なくとも執筆時点では。GitHub Issue #7138 は、40 KB のファイルが警告なしに 32 KB へ黙って切り詰められることを記録しており、「not planned」としてクローズされています。対照的に Claude Code は、コンテキストファイルが予算を超えると警告します。覚えておく価値のある違いです。
Codex は設定をどこに保存しますか？
CODEX_HOME ディレクトリの中で、既定は ~/.codex です。config.toml、auth.json、history.jsonl を保持します。環境変数を使って CODEX_HOME を別のディレクトリに向けることができます。
まとめ
Codex の AGENTS.md の仕組みは、突き詰めれば 3 つです。固定された検索順序（グローバル、次に git-root から cwd まで）、ルートから下への連結（衝突したときはあなたに最も近いファイルが勝つ）、そして32 KiB の上限（あふれた分を黙って捨てる）。そして、そのどれも CLAUDE.md には一切触れません。シンプルに書き、巨大なひとつのルートファイルに詰め込む代わりにディレクトリごとに分割すれば、落とし穴も無駄なコストも避けられます。そもそもなぜ長いファイルが役に立たないのかについては、AGENTS.md vs CLAUDE.md — そして長いファイルは本当に効果があるのかを参照してください。