Codex の AGENTS.md を、置き場所を変えながら同じ依頼で動かして比較検証を行いました。

結論からお伝えすると、グローバルとリポジトリ直下の AGENTS.md は双方とも読み込まれ、指示が衝突した場合はリポジトリ直下の設定が優先されました。

サブフォルダ配下の AGENTS.md については、Codex をどのフォルダで起動したかによって読み込まれ方が変化しました。

併せて、2026 年 9 月から AGENTS.md を読み込むようになった Claude Code でも同様のフォルダ構成で検証を行い、OpenAI が推奨する「モデル変更時には AGENTS.md を見直す」という運用指針についてもまとめています。

検証日は 2026 年 10 月 2 日、環境は macOS 15.7 です。Codex CLI 0.160.0（デフォルトモデル: gpt-6.1-sol）と Claude Code 2.1.283 を使用しました。

なお、Codex はコマンドラインで操作する CLI 版のみで検証を行っており、Codex アプリでの検証は実施していません。

AGENTS.md と config.toml の役割(公式の説明)

AGENTS.md は、Codex が作業を開始する前に読み込む「作業ルールのメモ」です。

公式ドキュメント「Custom instructions with AGENTS.md」（2026 年 10 月 2 日確認）によると、読み込みの場所および順番は以下の通りです。

各ファイルは上から順番に結合されて渡され、作業フォルダに近い階層のものほど後ろに配置されるため優先される、という仕組みです。

このほか、一時的に設定を差し替える AGENTS.override.md や、合計 32KiB という容量制限が存在します。

もう一方の設定ファイルである ~/.codex/config.toml は、モデルや実行権限などを定義するファイルであり、AGENTS.md の別名指定や上限値の変更もここから設定できます。

4 つの置き場所を同じ依頼で比べた手順

AGENTS.md の効果が視覚的に判別できるよう、置き場所ごとに「目印」と「担当」を変更した AGENTS.md を 3 つ作成しました。

普段使用している ~/.codex/AGENTS.md を直接変更することを避けるため、環境変数 CODEX_HOME を使用して Codex の設定フォルダを検証用の ~/agents-md-demo-codex-home へ切り替えました。

CODEX_HOME を切り替えることで、その内部にある AGENTS.md がグローバル設定として扱われます。

検証の手順は以下の通りです。

1. ~/agents-md-demo を作成して git init を実行し、内部に sub フォルダを作成する
2. 検証用の設定フォルダ ~/agents-md-demo-codex-home を作成し、認証情報である auth.json のみを本物の環境からシンボリックリンクする
3. グローバル、リポジトリ直下、sub の各場所に上図の AGENTS.md を配置する（検証ケースに応じて配置・非配置を切り替える）
4. CODEX_HOME=~/agents-md-demo-codex-home を指定した上で、npx -y @openai/[email protected] exec -s workspace-write "hello.txt を作り、自己紹介を1行書いてください。" を実行する
5. 出力された返答の 1 行目にある「担当」と、生成された hello.txt に付与された「✓」の記述を確認する

「✓」の記述は複数の指示が同時に適用（加算）されるルールであり、「担当」はどれか 1 つのみが適用される非両立のルールです。

この 2 種類の記述を見ることで、「指示が統合・加算されるのか」および「指示が衝突した際にどちらが優先されるのか」を判定しました。

グローバルと直下の AGENTS.md は足し算され、ぶつかると直下が勝った

4 パターンの配置条件において、同一の依頼を 1 回ずつ実行しました。

グローバルと直下の両方に配置した場合、✓ の記述は双方とも付与され、担当には直下で指定した「いぬ」が採用されました。

公式の仕様通り、両方の設定ファイルを読み込んだ上で、競合する指示については作業フォルダにより近い側の設定が適用されています。

なお、グローバルのみ配置したケースでは、自己紹介のテキストまで「私はねこです。」となっており、少し微笑ましい結果となりました (´・ω・`)

「最後の行に」と書いたら、片方の目印が消えた

当初の検証では、グローバルと直下の双方の指示書に「ファイルを作成する際は、最後の行に「✓〜」と記載すること」という条件を記述していました。

この条件でグローバル + 直下の構成を試したところ、hello.txt に付与されたのは「✓ リポジトリのルール」の 1 行のみという結果になりました。

「最後の行」という位置指定は 1 箇所しか存在しないため、2 つの指示が競合し、より優先度の高い直下の設定が勝ち残った形です。

グローバルと直下の AGENTS.md に同種のルールを定義する場合は、双方の指示が衝突せず両立できる表現になっているか確認しておく必要があります。

読み込まれた中身はセッションログで確かめられる

Codex は実行毎に、CODEX_HOME 内の sessions フォルダへセッションログ（rollout-*.jsonl）を出力します。

このログ内の agents_md というフィールドに、モデルへ実際に注入された AGENTS.md の結合テキストが格納されていました。

グローバル + 直下の構成では、グローバル記述の末尾に --- project-doc --- というセパレーターが挿入され、それに続いて直下の内容が結合されていました。

一方で、モデルに対して「読み込んだ指示ファイルを順番に一覧化してください」と質問したところ、正確なファイルパスは返答されませんでした。

3 つの AGENTS.md が配置された状態で質問した際も、/Users/ma/agents-md-demo/sub/AGENTS.md の 1 つのみを提示し、「各ルールがどの別ファイルから読み込まれたかや、その読み込み順序は、提示された情報のみからは特定できません。」という趣旨の回答が返ってきました。

公式ドキュメントには「List the instruction sources you loaded.」と質問して確認する方法が掲載されていますが、モデル側に引き渡されるのは結合後のプロンプトテキストのみであり、ファイルごとのパス情報までは付与されていないようです。

どの設定ファイルが適用されているかを正確に検証したい場合は、固有の目印を仕込むか、セッションログを直接確認する方が確実です。

サブフォルダの AGENTS.md は、起動したフォルダで読まれ方が変わった

グローバル・直下・sub の 3 箇所すべてに AGENTS.md を配置し、以下の 2 パターンで挙動を検証しました。

1. リポジトリ直下で起動し、「sub/hello.txt を作り、自己紹介を 1 行書いてください。」と依頼する
2. -C ~/agents-md-demo/sub（--cd の省略形）で sub を作業ディレクトリに指定して起動し、「hello.txt を作り、自己紹介を 1 行書いてください。」と依頼する

いずれのケースも、最終結果としては 3 つの ✓ マークが付与され、担当表記は「うさぎ」となりました。

しかし、内部の実行プロセスを確認すると、その理由は全く異なるものでした！

sub ディレクトリで起動したパターン 2 の場合、セッションログに「全体 → リポジトリ → サブフォルダ」の順で結合された AGENTS.md が記録されており、Codex のシステム仕様として正しく読み込まれていました。

一方、直下で起動したパターン 1 の場合、セッションログに記録されていたのはグローバルと直下の 2 ファイルのみであり、sub/AGENTS.md はシステムとして読み込まれていませんでした。

それにもかかわらず目印が付与されたのはなぜでしょうか？

実行ログを解析したところ、モデル自体が自発的にファイル検索コマンド rg --files -g AGENTS.md を実行して sub/AGENTS.md を発見し、cat コマンドでその内容を読み取った上で処理を行っていたことが判明しました。

そのため、初期の応答は「担当: いぬ」で開始され、sub/AGENTS.md を閲覧した後の最終応答で「担当: うさぎ」へと更新されていました。

同一の依頼を 3 回実行したところ全て同様の挙動となりましたが、これはあくまでモデルの自律的な判断によるものであるため、異なるモデルやプロンプト内容においても同様の結果になるかどうかの保証はありません。

サブフォルダ固有のルールを確実に適用させたい場合は、該当フォルダで Codex を起動するのが最も確実な運用方法です。

Claude Code も AGENTS.md を読むようになった(v2.1.277〜)

Claude Code は従来 CLAUDE.md のみを読み込む仕様でしたが、公式ドキュメントによると v2.1.277（npm でのリリースは 2026 年 9 月 18 日）以降、AGENTS.md も直接読み込むように機能拡張されました。

公式ドキュメントに書かれている条件

Claude Code の公式ドキュメント（How Claude remembers your project 内 AGENTS.md の項、2026 年 10 月 2 日時点）に記載されている条件は以下の通りです。

• Claude Code v2.1.277 以降が必須
• v2.1.281 未満のバージョンでは、Amazon Bedrock 経由での利用時やテレメトリが無効化されている環境などで読み込み不可
• 作業ディレクトリおよびその上位ディレクトリに CLAUDE.md（.claude/CLAUDE.md、CLAUDE.local.md を含む）が存在しない場合のみ、AGENTS.md を読み込む
• サブフォルダ内の AGENTS.md は、そのフォルダ配下のファイルをアクセス・参照したタイミングでロードされる
• AGENTS.override.md や AGENTS.local.md の読み込みには非対応

ユーザーグローバルの指示設定については ~/.claude/CLAUDE.md で管理する仕様となっており、Codex の ~/.codex/AGENTS.md に相当する「ユーザー全体の AGENTS.md」は読み込み対象として定義されていません。

Codex と同じフォルダで試した結果

Codex の検証で使用した AGENTS.md をそのまま利用し、Claude Code 2.1.283（デフォルトモデル: Claude Opus 5.5）で検証を行いました。

1. ~/agents-md-demo ディレクトリへ移動する
2. claude -p --permission-mode acceptEdits "hello.txt を作り、自己紹介を1行書いてください。" のように、Codex と同一の依頼文で実行する
3. 出力返答の 1 行目と、生成されたファイルの目印を確認する

リポジトリ直下に AGENTS.md のみを配置した状態では、Codex と同様に「担当: いぬ」および「✓ リポジトリのルール」が適用されました！

実際の ~/.codex/AGENTS.md が存在する状態で、AGENTS.md を配置せずに「最初から与えられている指示ファイルはあるか」と質問したところ、「最初から渡された指示ファイルはありません。」という回答が得られました。

Claude Code は、Codex 向けのグローバル AGENTS.md を読み込まない仕様であることが確認できます。

続いて直下と sub に AGENTS.md を配置し、直下で起動して sub/hello.txt を生成させたところ、「担当: うさぎ」と 2 つの ✓ マークが付与されました。

実行ログを確認すると、Claude Code についても Codex と同様に、モデル自らが sub ディレクトリ内を探索し、sub/AGENTS.md を開いて読み込んでいました。

そこで、モデルが自発的に AGENTS.md を閲覧できないよう、使用可能ツールをファイルの読み書きのみに限定した上で、「sub/memo.txt を読んで、内容を 1 行で要約した sub/summary.txt を作って」と依頼しました。

この時 Claude Code が実施した操作は sub/memo.txt の読み込みと sub/summary.txt の書き込みの 2 点のみでしたが、生成された summary.txt にはサブフォルダの ✓ マークが付与され、応答も「担当: うさぎ」となりました。

公式ドキュメントに記載されている通り、サブフォルダ内のファイルを読み込んだ時点で、同階層の AGENTS.md が自動的にロードされる挙動が実証されました。

CLAUDE.md があると AGENTS.md は読まれなかった

では、CLAUDE.md と AGENTS.md が同階層に併存している場合はどうなるでしょうか？

リポジトリ直下の AGENTS.md と同じ場所に、「✓CLAUDE.md」および「担当: ぺんぎん」を指示する CLAUDE.md を配置しました。

デフォルト設定のまま実行した場合、反映されたのは「✓CLAUDE.md」のみであり、AGENTS.md 側の指示は完全に無視されました。

公式ドキュメントにある「Project instructions」の設定値を claude-md-and-agents-md に変更することで、双方のファイルを読み込ませることが可能となります。

今回は起動時に以下の設定パラメータを付与して試行しました。

claude -p --settings '{"pluginConfigs":{"agents-md@builtin":{"options":{"instructionFiles":"claude-md-and-agents-md"}}}}' "hello.txt を作り、自己紹介を1行書いてください。"

この設定オプションを指定した場合、2 つの ✓ マークがともに付与され、担当指示が競合した際には CLAUDE.md 側の「ぺんぎん」が優先採用されました。

公式ドキュメントによると、この設定は /config 内の Project instructions または ~/.claude/settings.json から変更可能であり、プロジェクト内部の設定ファイルに記述しても無効化される仕様とのことです。

Codex と併用しており、すでに CLAUDE.md が存在するリポジトリにおいては、単に AGENTS.md を追加配置するだけでは Claude Code に反映されないため注意が必要です。

Claude Code と Codex の併用連携については、Claude Code と Codex の連携方法の記事でも解説しています。

モデルが変わったら AGENTS.md を見直す(OpenAI Developers Blog、2026-09-11)

OpenAI Developers Blog の記事「Rethinking skills and prompts for GPT-6 Astra」（Eric Provencher、2026 年 9 月 11 日）では、モデルのバージョンアップに伴い、AGENTS.md を含む各種指示書を定期的に再評価・改訂することを推奨しています。

With each release, it's been worth revisiting those assumptions, but with GPT-6 Astra, it's more important than ever

Because AGENTS.md applies whenever the model works in your repository, you should frequently revisit each instruction

その具体的な理由として、以下の例が挙げられています。

Previous models needed encouragement to run tests and check their work. GPT-6 Astra does that on its own, so the same instructions can lead to unnecessary testing

Requiring a stack of docs or a full repo map before every edit is excessive for a typo fix

従来モデルでは「必ずテストを実行して結果を確認すること」「作業前に資料を一読すること」といった明確な念押しが必要でしたが、最新モデルではこれらの工程を自発的に遂行するため、従来の指示が残っていると冗長なテストや不要な処理を誘発してしまう、という指摘です。

モデルの世代交代は急速に進行しており、Codex CLI 0.159.1（2026 年 9 月 29 日リリース）のリリースノートにおいて、デフォルトモデルが GPT-6.1 Sol にアップデートされたことが明記されています。

今回 config.toml でモデルを明示的に指定せず 0.160.0 を実行した際も、実際の内部モデルには gpt-6.1-sol が割り当てられていました。

ユーザー自身が明示的に変更操作を行っていない場合であっても、CLI の更新に伴って自動的に使用モデルが変更されているケースが存在します！

古い書き方の AGENTS.md を点検させてみた

ブログの事例に沿った「旧世代向けの記述」を含む AGENTS.md を作成し、Claude Code 2.1.283 の /doctor prompt-audit 機能でコード診断を実施しました。

公式ドキュメントによると、この機能は過去の旧モデル向けに記述された過剰な指示や、実在しないファイルパスへの参照などを自動検知するものであり、ファイルの直接書き換えは行わず、監査レポートと改善提案のみを出力する仕組みです。

「いかなる軽微な修正であっても docs/ 配下の全ファイルを閲覧すること」という記述に対しては、高い確信度（確信度: 高）で削除が提案され、そもそも docs/ ディレクトリが存在しない旨の指摘も行われました。

また、「必ずすべてのテストを実行し、その結果を複数回確認すること」という記述については、同一結果の重複確認は追加情報をもたらさないとして、表現の修正案が提示されました。

診断完了後に AGENTS.md のファイル内容を確認したところ、指定通り改変は行われていませんでした。

ただし、この監査処理は実行中の Claude モデルの基準に基づいて評価される旨がレポートに明記されているため、Codex の GPT-6 系向けに指示を最適化する場合は、ブログで提示された観点を踏まえて人間側での手動再確認を行う必要があります。

見直すときに確かめること

ブログの提言および今回の監査結果を踏まえると、指示書を見直す際は以下の 3 点を確認するのが効果的です。

• 「必ず」「繰り返し」といった強制・重複の念押しが、最新モデルにとって不要なオーバーヘッドとなっていないか
• 「作業前に全ファイルを読破する」のように、軽微な修正作業に対しても過剰に重い手順を義務付けていないか
• 存在しないディレクトリや非推奨コマンドなど、現在のプロジェクト構成と乖離した記述が残留していないか

置き場所ごとの効き方の一覧

グローバルと直下に配置した AGENTS.md は加算（統合）されて評価され、指示が競合した場合はより作業ディレクトリに近い側の設定が優先されます。

サブフォルダのルールについては、Codex では当該フォルダで起動した場合にシステムとして確実に機能し、Claude Code では該当フォルダ配下のファイルをアクセスした時点で読み込まれます。

モデルや CLI ツールのアップデートが行われた際は、AGENTS.md 内の過剰な制約や重い手順設定が現在も必要であるかを定期的に見直すことを推奨します (^^)