Claude CodeがAGENTS.mdを読まない条件

Codexなど他のAIコーディングツールに合わせて、リポジトリの指示をAGENTS.mdに書いているチームは、Claude Codeにも同じ指示が効いているのかが気になるはずです。外部の開発会社にリポジトリを渡す側なら、相手のツールに関係なく規約が伝わるのかも確かめたいところです。実は、AGENTS.mdとCLAUDE.mdが両方あると、Claude Codeは標準ではAGENTS.mdを読みません。

公式ドキュメントの読み込み条件と、2026年9月29日にClaude Code 2.1.284で試した4つの組み合わせの結果を並べ、確かめ方と、指示を1本にまとめる方法を整理します。

CLAUDE.mdが無いときだけAGENTS.mdを読む

CHANGELOGによると、2.1.277（npm公開は2026年9月18日）で「CLAUDE.mdの無いプロジェクトでは代わりにAGENTS.mdを読む」対応が入りました。2.1.281（同9月23日）で、Amazon Bedrock、Google Vertex AI、Microsoft Foundry、LLM gateway経由と、テレメトリを無効にしたセッションにも広がっています。公式ドキュメントも、v2.1.281より前はこうしたセッションがCLAUDE.mdしか読まないと書いています。

判定に使うのは、作業ディレクトリとその上位にあるファイルです。

• 数えられる（あればAGENTS.mdの代わりに読む）: CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md
• 数えられない（AGENTS.mdと並んで読まれる）: 各自の ~/.claude/CLAUDE.md、組織のmanaged CLAUDE.md、.claude/rules/ のファイル

ホームに個人のCLAUDE.mdがあってもAGENTS.mdは読まれますが、リポジトリや親ディレクトリにCLAUDE.mdが1つでもあれば読まれません。

上3段は公式ドキュメントの表のとおりです。見落としやすいのは最下段で、個人用のCLAUDE.local.mdも数えられるため、足した時点でAGENTS.mdが外れます。

条件を満たすと、作業ディレクトリと上位にあるすべての AGENTS.md と .claude/AGENTS.md がセッション開始時に読まれ、中の @path のimportも展開されます。一方、AGENTS.local.md、AGENTS.override.md、.agents/ ディレクトリの中は読まれません。他のツール向けにそこへ書いた指示は、Claude Codeには届きません。組み込みの agents-md プラグインを /plugin で無効にした場合も、CLAUDE.mdだけを読みます。

4つの組み合わせを実際に試した

2026年9月29日に、Linux上のClaude Code 2.1.284を非対話モード（claude -p）で起動し、ケースごとに git init したディレクトリで各1回試しました。AGENTS.mdには合言葉「KUMQUAT-41」と、そこにだけ書いたテストコマンド npm run verify を、CLAUDE.mdには別の合言葉「PERSIMMON-9」を置いています。

1. AGENTS.mdだけ: 合言葉は KUMQUAT-41。AGENTS.mdが読まれました。
2. AGENTS.md＋CLAUDE.md（importなし）: 合言葉は PERSIMMON-9、テストコマンドは NONE。AGENTS.mdは読まれていません。
3. CLAUDE.mdの先頭で @AGENTS.md をimport: テストコマンドは npm run verify、合言葉は PERSIMMON-9。食い違いに触れたうえで、Claude固有の指示としてCLAUDE.md側を採ったと説明しました。
4. AGENTS.md＋CLAUDE.local.md（個人メモだけ）: テストコマンドは NONE。公式ドキュメントの記述どおり、AGENTS.mdが読まれなくなりました。

ケース3でCLAUDE.md側が採られたのは1回の観察で、仕様ではありません。矛盾時の優先順位を定めた記述は公式ドキュメントに見当たりません。

CLAUDE.local.mdの落とし穴と「Project instructions」

AGENTS.mdを正本にしているチームで、誰かが手元のメモとしてCLAUDE.local.mdを作ると、その人のClaude CodeだけがAGENTS.mdを読まなくなります。コミットされないファイルなので、他のメンバーからは原因が見えません。

公式ドキュメントは、この場合 /config の Project instructions を claude-md-and-agents-md にするよう案内しています。値は4つです。

設定ファイルでは pluginConfigs の agents-md@builtin の下に "options": { "instructionFiles": "claude-md-and-agents-md" } のように書きます。ただし有効なのは ~/.claude/settings.json、--settings で渡すファイル、managed settingsだけで、プロジェクトとローカルの設定ファイルでは無視されます。リポジトリにコミットして全員に配ることはできません。

どちらが効いているかを確かめる

1. claude --version で2.1.277以降か確認します。Bedrockやテレメトリ無効の環境では2.1.281以降が必要です。
2. 起動するディレクトリから上位に向かって、CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md を探します。親ディレクトリのものも数えられます。
3. 対話モードでは、no CLAUDE.md found; AGENTS.md loaded: ... のような行が会話に出ると公式ドキュメントにあります（今回この表示は確認していません）。
4. AGENTS.mdにだけ書いた事実を claude -p で聞きます。他のファイルに無い文字列を選ぶと、答えられたかどうかで判断できます。

正本を1本にまとめる運用（編集部の提案）

複数のツールを併用するリポジトリや、外部に渡すリポジトリでは、規約の本文をAGENTS.mdに置き、CLAUDE.mdは次の形にしておくことを提案します。公式ドキュメントが「他のツールと1つのファイルを共有する」方法として示している形です。

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

公式ドキュメントによると、どのProject instructionsの値でもimportでAGENTS.mdが二重に読まれることはなく、AGENTS.mdを直接読めないセッションでも効きます。受け取る側の個人設定やバージョンに左右されにくいのが利点です。ファイルごとの役割分担はAGENTS.md / SKILL.md / DESIGN.mdの役割分担で扱いました。

あわせて次の点を決めておくと、ずれが起きにくくなります。

• CLAUDE.mdに規約を重複して書かない。 2か所の記述が食い違うと、どちらが採られるかは保証されません。
• 以前の回避策を片付ける。 AGENTS.mdを出力するSessionStartフックは二重に読み込ませるので外し、「AGENTS.mdを読め」と文章で書いたCLAUDE.mdはimportに置き換えるよう、公式ドキュメントは案内しています。
• Windowsの利用者がいればシンボリックリンクより import。 リンクの作成に管理者権限か開発者モードが要り、Gitの設定によっては1行のテキストファイルとして取り出されます。

リポジトリを社外に渡す前は、AIコーディングツールが.git履歴ごと送っていた件とあわせて、指示ファイルと送信範囲を一度に点検すると効率的です。

2026年9月29日に、Claude Code Docs「How Claude remembers your project」のAGENTS.mdの節、Claude CodeのCHANGELOG（2.1.277・2.1.281）、npm registryの公開日時を直接開いて照合し、Claude Code 2.1.284の claude -p で4つのファイル構成を各1回試しました。対話モードの表示、/config の画面、pluginConfigs による設定変更、Bedrock・Vertex AI・Foundry・LLM gateway経由のセッション、サブディレクトリのAGENTS.md、Windows環境は検証していません。

AIコーディングツールを使う開発体制や自動化の設計は、グリームハブへご相談ください。

Sources

• How Claude remembers your project — Claude Code Docs
• CHANGELOG.md — anthropics/claude-code (GitHub)
• @anthropic-ai/claude-code — npm registry