AIコーディングガイド

Codex の AGENTS.md が途中までしか読まれない:project_doc_max_bytes と fallback ファイル名の設定

Codex 公開:

Codex が AGENTS.md を読み込む仕組み(探索順、AGENTS.override.md、既定 32 KiB の上限、フォールバックのファイル名)を整理し、project_doc_max_bytes と project_doc_fallback_filenames で上限とファイル名を変える方法を解説します。

検証日 2026年9月10日 仕様変更が早い分野です。最新の公式ドキュメントも併せてご確認ください。
#Codex#AGENTS.md#project_doc_max_bytes#config.toml#モノレポ
目次
  1. 探索順と連結のルール
  2. 32 KiB の上限
  3. ファイル名を変える
  4. 別の設定ディレクトリで切り替える
  5. まとめ

AGENTS.md に細かく書いたのに、後半の指示が効いていない。あるいは、チームが CLAUDE.md や TEAM_GUIDE.md で運用していて Codex 用に別ファイルを増やしたくない。どちらも Codex の AGENTS.md の読み込みルールを知ると解決します。

結論として、Codex は AGENTS.md をルートからカレントディレクトリに向かって連結し、合計 32 KiB(既定) に達したところで読み込みを止めます。上限は project_doc_max_bytes で、代替ファイル名は project_doc_fallback_filenames で変えられます。

KEY POINT

この記事で分かること

  • AGENTS.md の探索順(グローバル → プロジェクト)と AGENTS.override.md の役割
  • 既定 32 KiB の上限がどう効くかと、project_doc_max_bytes の変え方
  • project_doc_fallback_filenames で CLAUDE.md などを代わりに読ませる方法

探索順と連結のルール

公式ドキュメントによると、Codex は次の順で指示ファイルを集めます。

  1. グローバル: ~/.codex/AGENTS.override.md があればそれ、無ければ ~/.codex/AGENTS.md。この階層では最初に見つかった空でないファイル 1 つだけを使う
  2. プロジェクト: Git のルートからカレントディレクトリまで、各階層で AGENTS.override.md → AGENTS.md → フォールバックのファイル名 の順に探す
  3. 見つかったファイルをルート側から順に空行で連結する。カレントに近いファイルほど後ろに来るため、先の指示を上書きしやすい

空のファイルはスキップされ、探索はカレントディレクトリに到達した時点で止まります。カレントより下のディレクトリの AGENTS.md は読まれません。指示は実行のたびに組み立て直されるので、キャッシュの削除などは不要です。

用語解説

AGENTS.override.md: 同じ階層の AGENTS.md の代わりに使われるファイルです。共有の AGENTS.md をそのままに、自分だけの上書きを置きたいときに使います。gitignore に入れておくとチームに影響しません。

32 KiB の上限

読み込むバイト数の合計には上限があり、project_doc_max_bytes の既定は 32768(32 KiB)です。連結の途中で上限に達すると、それ以降のファイルは追加されません。ルートの AGENTS.md が大きいと、カレントディレクトリ寄りの AGENTS.md がまるごと落ちることになります。

# 既定は 32768。必要な分だけ増やす
project_doc_max_bytes = 65536
項目値
既定32768 バイト
対象グローバルとプロジェクトの指示ファイルの合計
超えたとき上限に達した時点で以降のファイルを追加しない

上限を増やす前に、AGENTS.md 自体を短くする方が効果的です。毎回は要らない手順は別ファイルにして「必要なときに読め」と書いておけば、Codex は作業中にそのファイルを読みに行けます。

ファイル名を変える

AGENTS.md が無いディレクトリで代わりに探すファイル名を、project_doc_fallback_filenames に順番に並べます。

project_doc_fallback_filenames = ["CLAUDE.md", "TEAM_GUIDE.md", ".agents.md"]

これで、Claude Code 用の CLAUDE.md を置いているリポジトリでも、Codex がそれを指示として読みます。探索順は各階層で AGENTS.override.md → AGENTS.md → ここに並べた順 なので、AGENTS.md が存在する階層ではフォールバックは使われません。

Claude Code 側は AGENTS.md を読まない

逆方向は自動ではありません。Claude Code は CLAUDE.md だけを読むため、AGENTS.md を共通の指示にしたい場合は CLAUDE.md から @AGENTS.md で取り込む形にします。両ツールの指示ファイルの違いは コンテキストファイルの比較 にまとめています。

別の設定ディレクトリで切り替える

CI や自動化用に別の AGENTS.md を使いたい場合は、環境変数 CODEX_HOME で設定ディレクトリごと切り替えられます。$CODEX_HOME/AGENTS.md がグローバルの指示として読まれるので、用途ごとにディレクトリを分けておくと安全です。

AGENTS.md に何を書くかは親記事の Codex CLI のセットアップと AGENTS.md の書き方 を、config.toml の全体像は config.toml でモデル・推論の深さ・プロファイルを切り替える を参照してください。

まとめ

  • AGENTS.md は ~/.codex/ → Git ルート → カレントディレクトリ の順に集められ、ルート側から連結される。カレントより下は読まれない
  • 各階層で AGENTS.override.md が AGENTS.md より優先される
  • 合計 32 KiB(project_doc_max_bytes = 32768)を超えると、以降のファイルは追加されない。増やすより短くする
  • project_doc_fallback_filenames で CLAUDE.md などを代わりに読ませられる
  • CODEX_HOME を分けると用途別のグローバル指示を使い分けられる

よくある質問

AGENTS.md はどこまで読まれますか?
既定では合計 32 KiB(project_doc_max_bytes = 32768)までです。ルートからカレントディレクトリに向かって連結し、上限に達した時点でそれ以降のファイルは追加されません。
AGENTS.md という名前以外のファイルを読ませられますか?
はい。project_doc_fallback_filenames に候補を並べると、そのディレクトリに AGENTS.md が無いときに順番に探します。
AGENTS.override.md は何ですか?
同じディレクトリに AGENTS.override.md があると、AGENTS.md より優先して使われます。個人用の上書きやローカル検証に使えます。

参考にした一次情報

この記事は公式ドキュメントを基に AI が下書きを作成し、運営者が内容を確認して公開しています。誤りを見つけた場合は お問い合わせからお知らせください。

関連記事