CodexのAGENTS.mdの書き方｜指示を分割して保守する設計

2026年8月8日時点のOpenAI公式ドキュメントでは、Codexは作業前にAGENTS.mdを読み、実行ごとに指示チェーンを組み立てます。TUIでは通常、起動したセッションごとに一度です。したがって、AGENTS.mdは人間向けの補足文書というより、Codexが作業判断に使う永続的なプロジェクト指示として設計します。

探索は三段階で考えると整理できます。最初はグローバルスコープです。Codexホームは既定で`~/.codex`であり、`AGENTS.override.md`があればそれを、なければ`AGENTS.md`を読みます。この階層で採用されるのは、最初の空でないファイルだけです。個人がどのリポジトリでも守りたい作業上の好みは、ここに置く対象です。

次がプロジェクトスコープです。Codexは通常Gitルートであるプロジェクトルートから、現在の作業ディレクトリまで下りながら探索します。プロジェクトルートを特定できない場合は、現在のディレクトリだけを確認します。各階層では`AGENTS.override.md`、`AGENTS.md`、設定した代替ファイル名の順に探し、採用するのは最大1ファイルです。

最後に結合順があります。読み込んだ内容はルート側から順番に連結され、現在の作業ディレクトリに近い指示ほど後ろに置かれます。競合時に近い指示が優先されるのは、この順序によるものです。配置場所によって、指示が効く範囲と優先順位が決まります。

AGENTS.mdに向くのは、Codexが実装やレビューの途中で繰り返し参照する情報です。たとえば、セットアップ方法、変更後に実行するテスト、採用するパッケージマネージャー、生成物を直接編集してよいか、レビューで重視する不具合、変更してはいけない境界が該当します。コマンドは`テストを行う`のような抽象表現を避け、実際に実行できる形で記述すると解釈の幅を減らせます。

設計思想の長い歴史、製品紹介、APIの網羅的な説明まで転記すると、作業指示と参考情報の境目がぼやけます。READMEや設計文書が正本なら、その文書への参照と、Codexがいつ読むべきかを短く書くほうが保守しやすくなります。AGENTS.mdへの仕様の複製は、更新漏れによって正本を二つに増やします。

指示は観測できる形にします。`品質を高く保つ`だけでは、完了条件が分かりません。対象に合うテストコマンド、型チェック、リンター、確認すべき差分を示せば、Codexも人間も同じ結果を確かめられます。ただし、CIが機械的に強制している書式規則をすべて文章へ写す必要はありません。OpenAI公式のコードレビュー向け説明も、フォーマットやlintの確認はCIに任せ、レビュー規則は簡潔にするよう案内しています。

大きなリポジトリでは、フロントエンドとAPI、アプリケーションとインフラで検証方法が変わります。ここでルートのAGENTS.mdへ条件分岐を足し続けると、すべての作業で無関係な指示まで読み込ませることになります。ルートには全体共通の原則を残し、コマンドや制約が変わるディレクトリにだけ局所ファイルを置くのが基本です。

同じ内容を局所ファイルにも再掲すべきか迷うかもしれません。共通ルールは局所ファイルへ再掲しません。Codexはルートから現在地までの指示を結合するため、すでに引き継がれます。配下には差分だけを書きます。たとえばルートで通常のテストを定義し、決済サービスだけ別コマンドが必要なら、そのサービス配下でテスト指示だけを置き換えます。

ディレクトリがあるたびにAGENTS.mdを作ると、更新箇所だけが増えます。局所ファイルを置く条件は、その配下で実際に判断が変わることです。所有チームが違っても、コマンドと制約が同じなら分割理由にはなりません。同じチームの管理下でも、デプロイ方法や安全境界が違う場所には分割する価値があります。

Codexの探索は現在の作業ディレクトリで止まります。リポジトリルートから起動して、まだ降りていない子ディレクトリの指示を当然に読む仕組みではありません。専門ルールを有効にしたい作業では、対象ディレクトリを現在地にするか、`codex --cd`で開始位置を指定し、読み込まれた指示を確認します。この性質まで含めて配置を決める必要があります。

`AGENTS.override.md`は、単なる追記ファイルではありません。同じディレクトリに通常の`AGENTS.md`があっても、Codexはoverrideを先に見つけ、その階層では片方だけを採用します。グローバルでは一時的な既定方針の差し替え、プロジェクト配下では特定スコープの指示を明示的に置き換える用途に向きます。通常ファイルとoverrideの両方が合成されると考えると、必要な共通事項が消えるので注意が必要です。

CLAUDE.mdと似た『エージェント向け指示ファイル』として扱うだけでは、Codex固有の設計を見落とします。名称の置換にとどめず、Codexがどの起点からどの階層を探索し、各階層でどのファイルを一つ選び、どの順に結合するかを設計します。既存のCLAUDE.mdをそのまま複製すると、二つのファイルが別々に更新され、規約が食い違う恐れがあります。

移行時は、まず共通規約の正本を決めます。Codexが直接必要とする短い判断基準はAGENTS.mdへ置き、長い共有仕様は既存文書へのリンクに寄せます。別名の既存ファイルをCodexにも読ませたい場合は、`project_doc_fallback_filenames`へ登録できます。ただし公式仕様では代替名は、各階層でAGENTS.mdが見つからない場合に試されます。AGENTS.mdと別名ファイルを同じ階層で両方読み込ませる設定ではありません。

複数エージェントで共有したい規約は、短いエージェント別入口から共通文書を参照する方法や、運用上許容できる場合の代替ファイル名設定によって更新点を絞れます。どの方式でも、各ツールの現行の探索仕様を前提に検証し、片方のファイル名に関する知識だけで挙動を推測しないことが大切です。

2026年8月8日時点の公式ガイドでは、空の指示ファイルは読み飛ばされ、結合した指示は`project_doc_max_bytes`の上限に達すると追加が止まります。ガイドに示された既定値は32KiBです。詳細設定ページも、この設定をAGENTS.mdから読む量の上限として案内しています。上限へ近づいたら、設定値を変える前にスコープで分割し、無関係な指示と重複を除きます。

失敗した作業のたびに注意書きを追加する前に、そのルールが現在も必要か、CIや型で強制できないか、既存の指示と競合しないかを確認します。機械で確実に判定できる制約は自動化し、AGENTS.mdには判断、例外、実行順を残します。文章量を増やさず、Codexが迷う地点に情報を集中できます。

変更後は新しいセッションで読み込みを確認します。公式ガイドは、リポジトリルートから現在の指示を要約させる方法と、`codex --cd subdir`で配下の有効な指示ファイルを確認する方法を示しています。指示チェーンは実行ごと、TUIではセッション開始時に組み直されるため、古いセッションで修正結果を判断しないほうが確実です。

レビューでは文章と配置の両方を差分として扱います。ルートの指示変更は広い範囲へ影響し、配下の変更はそのサブツリーへ影響します。局所的な例外をルートへ足していないか、共通化した指示が配下に残っていないか、overrideが通常ファイルを意図せず隠していないかを確認します。

Codex向けAGENTS.mdは、リポジトリルートに全体共通のセットアップ、検証、レビュー、安全境界を置き、作業判断が変わるサブツリーにだけ差分を分けます。グローバル設定は個人の既定方針、`AGENTS.override.md`は同じ階層の通常ファイルを置き換える用途として区別します。これが、どこに置き、何を書き、どう分割するかへの具体的な答えです。

冒頭に残した条件は境界でした。分割数や組織図に合わせず、コマンド、制約、完了条件が変わる場所に引きます。Codexの探索順と現在の作業ディレクトリを基準にすれば、どの指示が効くかを説明でき、読み込み結果も新しいセッションで確認できます。CLAUDE.mdの名前だけを置換せず、Codexのスコープに合わせて重複のない指示チェーンを設計することが、長く保守できる書き方です。