CLAUDE.mdとAGENTS.mdはどこまで読まれる？モノレポで実測

Claude Codeは、起動した場所までのCLAUDE.mdと、作業中に読むサブディレクトリのCLAUDE.mdを、異なるタイミングで読み込みます。AGENTS.mdにも対応していますが、既定では起動場所やその上にCLAUDE.md系のファイルがあると、そちらを使います。「モノレポの全指示が起動時に入る」「AGENTS.mdは常に無視される」のどちらも、今回の判断基準にはできません。

要点

• ルートから起動しただけでは、a・bのCLAUDE.mdは読込イベントに現れませんでした。aの通常ファイルをReadすると、aのCLAUDE.mdが追加されました。
• Gitルートの一つ上のCLAUDE.mdも読み込まれました。Gitの境界だけでは指示を隔離できません。
• 7段のimport連鎖では4段目までを観測しました。標準出力・標準エラーに、深さ制限の警告はありませんでした。
• Codexはルートと起動ディレクトリまでのAGENTSの合言葉を返しました。Claude側のhook観測と、Codex側のモデルの返答は、証拠の種類を分けて読みます。

確認日：2026-10-26（Asia/Tokyo）。対象：Claude Code 2.1.308 / codex-cli 0.163.0、macOS。公式文書は同日取得した版番号のない現行ページです。別バージョン、全設定、AIの指示遵守を保証する測定ではありません。

#モノレポのどのファイルを、どう測ったか？

/tmpの下に、Gitルート、その親、packages/a、packages/bを作りました。macOSの実パスでは/private/tmpです。ファイルごとに異なるCANARY_の合言葉を入れ、通常ファイルには合言葉を入れていません。

fixture/
├── CLAUDE.md                 CANARY_PARENT_CLAUDE
├── AGENTS.md                 CANARY_PARENT_AGENTS
└── repo/                     git initした境界
    ├── CLAUDE.md             CANARY_ROOT_CLAUDE + @imports/1.md
    ├── AGENTS.md             CANARY_ROOT_AGENTS
    ├── CLAUDE.local.md       CANARY_LOCAL_CLAUDE
    ├── .claude/CLAUDE.md     CANARY_DOT_CLAUDE
    ├── imports/1.md → … → 7.md
    └── packages/
        ├── a/CLAUDE.md・AGENTS.md・probe.txt
        └── b/CLAUDE.md・AGENTS.md・AGENTS.override.md

ClaudeではInstructionsLoaded hookから、fixture内のファイル名、scope、load_reason、import元を保存しました。session_startは起動時、includeはimport、nested_traversalはサブディレクトリへのアクセスで追加されたイベントです。hookは非同期なので、ログの行順をコンテキストの連結順と解釈しません。hookの公式仕様

モデルにも、既に渡された指示の合言葉だけを返すよう依頼しました。ただし、返答にないことは、未読込の証明にはなりません。特に、AGENTS.mdのネイティブ読込はこのhookを発火させないと公式資料にあります。Codex側では同等の読込イベントを取得していないため、JSONLの返答を公式の探索規則と照合する方法に限定しました。

#サブディレクトリのCLAUDE.mdは起動時に読まれるか？

今回のイベントは次のとおりです。親・ルート・.claude/CLAUDE.md・CLAUDE.local.mdの4ファイルは、3回ともsession_startでした。

ルート起動時にaの指示が見えなくても、それだけで設定ミスとは言えません。公式資料も、子ディレクトリの指示は、その中のファイルを読み書きするときに読み込むと説明しています。メモリの公式資料

一方、packages/aからの起動では、祖先のCLAUDE.mdは読まれたのにimportのイベントがありませんでした。今回、この差の原因は特定していません。公式資料には、起動ディレクトリの外へ解決されるimportには承認が必要という条件があります。非対話実行と外部importの承認状態も、再現時に記録してください。

#AGENTS.mdは無視されるのか、CLAUDE.mdと両方読まれるのか？

現在の公式資料では、Claude Code v2.1.277以降にAGENTS.md対応があります。 既定のclaude-md-or-agents-mdでは、起動場所とその祖先にCLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdのいずれかがあると、CLAUDE側を選びます。ユーザー用の~/.claude/CLAUDE.mdは、この選択条件には数えません。

今回の混在した配置では、Claudeの返答にAGENTS側の合言葉は出ませんでした。これは既定設定の説明と一致します。ただし、AGENTSだけの配置や、両方を読む設定は実測していません。hookにAGENTSが現れないことだけで、無視されたと判定しないでください。AGENTS.mdの条件と設定

両方を必要とする場合、公式資料には/configのProject instructions、または--settingsへ渡す次の設定があります。project/local設定ファイルでは、このplugin設定を読まないという条件にも注意が必要です。下は公式設定の例で、今回実行した設定ではありません。

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

#@importは何段まで進み、止まると警告が出るか？

ルートのCLAUDE.mdを0段目として、@imports/1.mdから7.mdまで連鎖させました。repoで起動した2回のイベントは、1・2・3・4.mdまでがincludeで、5・6・7.mdのイベントはありません。合言葉の返答も1〜4まででした。公式資料の「最大4 hop」と一致します。

その2回とも標準エラーは0バイトで、通常の返答にも深さ制限の警告はありませんでした。debugログの深さ制限に関する語句検索も該当なしです。これを、すべてのUI・版で警告が出ないという保証へ広げません。深い連鎖を前提にせず、読み込ませたいファイルのイベントを確認する方が確実です。

なお、@pathはそれを記述したファイルからの相対パスです。コードブロックやインラインコードの中の@AGENTS.mdはimportされません。importの公式仕様

#CodexのAGENTS.md探索は、Claude Codeと何が違うか？

次は公式資料と今回の測定を分けた比較です。「下位が優先」は、上位の文章全体が削除される意味ではありません。Codexの公式資料も、探索したファイルを連結し、後に現れる指示を優先すると説明しています。Codexの公式探索規則

Codexの実際の返答は、ルート起動がCANARY_ROOT_AGENTS、a起動がそれとCANARY_A_AGENTS、b起動がルートとCANARY_B_OVERRIDEでした。bの通常AGENTS.mdの合言葉は返っていません。ツール実行は観測されませんでした。サイズ境界、競合する文章の遵守、cwdを途中で変えた場合は未検証です。

#同じ正本を両方へ渡し、手元で再現するには？

Claude固有の追記も必要なら、共通の本文をAGENTS.mdに置き、隣のCLAUDE.mdからimportする方法があります。これは公式資料が示す構成です。今回の実験では、この共有構成自体は実行していません。

# CLAUDE.mdの実際のファイル内容
@AGENTS.md

# この下にClaude固有の指示を書く

ファイルの内容にバッククォートやコードの囲みは含めません。Claude固有の追記がなければ、ln -s AGENTS.md CLAUDE.mdという選択肢も公式資料にあります。Windowsのsymlink権限・Git設定や、リンク先を編集する必要がある点を確認して選びます。import・symlinkとも、実環境の次のセッションで確認が必要です。

測定を再現するには、配布スクリプトを保存し、既存ログイン済みのClaude CodeとCodex、Node.js 22以降、GitがあるMacで実行します。

claude --version
codex --version
node instruction-discovery.mjs --create-only  # 合成ファイルだけ作る
node instruction-discovery.mjs --run          # 別の合成fixtureで測定する
shasum -a 256 instruction-discovery.mjs

実際の引数・抽出した返答・fixture内のイベントもJSONで配布します。共有記録では起動時のマシン設定と生debugを除いています。

配布ファイルのSHA-256：7bd46337e5018c96e0ed7770423ecaf099821d52b25e4937ab22b52217a6bfea。

--runはClaude 3回・Codex 3回の非対話呼出しを行います。既存の認証を使い、結果を含むfixtureは削除せず残します。通常の利用枠・API費用は使う認証の条件に従います。Claudeのユーザー設定・外部の指示ファイル・MCPを除外し、Read対象を合成probe.txt一つに限定します。Codexはユーザーconfigを除外したread-only実行で、ツールを使わない返答を依頼します。global指示やmanaged policyの完全な隔離を証明する実験ではありません。

結果ディレクトリのcommands.jsonにcwd・引数・終了コード、*.hooks.jsonlにfixture内の読込イベント、*.stdout.txtと*.stderr.txtに出力が残ります。実際のClaude呼出しには-p --setting-sources project,local --settings <fixture>/settings.json --debug-file <fixture>/results/<case>.debug.txtを使っています。空の--setting-sourcesは今回の予備試行でproject memoryを無効にしたため、使用していません。生debugにはマシン設定が含まれ得るので、共有するのはfixture内の必要な記録に絞ります。

次の作業へ渡すときは、CLI版、cwd、読込設定、見えたイベント、未確認の条件を残します。一件の作業状態とファイルの版はコンテキスト引き継ぎ、接続先の選択はMCP設定、処理を止める検査はHooksの終了コードで扱います。指示の文章がコンテキストに入ったことと、操作を強制的に止められることを分けて確認してください。