- 導入:なぜAGENTS.mdなのか
- 検証環境
- コピペ用プロンプト集
- 手順1(無料・10秒で完結):自分の手元バージョンがAGENTS.md対応か確認する
- 手順2:AGENTS.mdが本当にプリロードされているかを確かめる(ナイーブな検証法の罠)
- 手順3:CLAUDE.mdとAGENTS.mdが両方あるとどちらが勝つか
- 手順4:両方を読ませたい場合の設定(instructionFiles)
- 手順5(つまずき所その3):同じ設定を.claude/settings.json(プロジェクト共有設定)に書くと無視される
- 手順6(つまずき所その4):空のCLAUDE.local.mdが黙ってAGENTS.mdをブロックする
- synthesis:複数ツール共存プロジェクトへの統合フロー
- 活用例
- 注意点
- まとめ
導入:なぜAGENTS.mdなのか
AGENTS.mdは、Codex CLIやCursor、Windsurf、Clineなど複数のAIコーディングエージェントが共通で読みに行く「プロジェクト指示書」の事実上の標準フォーマットになりつつある。複数のAIツールを併用しているチームやOSSプロジェクトでは、「ツールごとに別の指示ファイルを書く」ことを避けたいというニーズが強い。
Claude Codeは2026-09-18公開のv2.1.277で、このAGENTS.mdをCLAUDE.mdの代わりとして直接読み込む機能を追加した(公式CHANGELOG.mdに明記)。しかし公式ドキュメント「How Claude remembers your project」(https://code.claude.com/docs/en/memory 、2026-09-18更新)を読むと、単に「読めるようになった」だけでなく、
- CLAUDE.mdとどちらが優先されるか
- 両方を読ませたいときにどう設定するか
- その設定がどこに書くと効いて、どこに書くと無視されるか
- 空の
CLAUDE.local.mdが置いてあるだけでAGENTS.mdが読まれなくなる
といった、実際に運用して初めて踏む落とし穴が複数ある。本記事では手元の旧バージョン(v2.1.270)と、npm install --prefixで隔離導入した新バージョン(v2.1.277)を使い捨てGitリポジトリ上で対照実験し、これらの仕様を実際のJSON出力で裏付ける。
検証環境
- 手元の既存インストール: v2.1.270(要求バージョンv2.1.277に未到達)
- 新バージョン:
npm install @anthropic-ai/claude-code@2.1.277 --prefix /tmp/agentsmd-test/new_cli --no-saveでグローバル環境を汚さず隔離導入 - 検証はすべて使い捨てGitリポジトリ上、非対話
claude -pで実行(実費は各手順に記載)
# 新バージョンの実体パス(node_modules配下)
/tmp/agentsmd-test/new_cli/node_modules/.bin/claude --version
# => 2.1.277 (Claude Code)
claude --version
# => 2.1.270 (Claude Code)
コピペ用プロンプト集
手順1(無料・10秒で完結):自分の手元バージョンがAGENTS.md対応か確認する
まずはこれだけ。課金なし、外部リソース不要で10秒以内に終わる。
claude --version
期待結果: 2.1.277以上ならAGENTS.mdを直接読める可能性がある。それより低ければ、後述のプロンプト2で示す通り「読めているように見えて実は毎回ファイル検索している」状態になっている可能性が高い。
成功判定: バージョン番号が出力される。2.1.277未満なら、AGENTS.mdを本当に自動読み込みしているかどうかは検証が必要(手順2へ)。
手順2:AGENTS.mdが本当にプリロードされているかを確かめる(ナイーブな検証法の罠)
つまずき所その1:「読めていますか?」と聞くだけでは分からない
最初にやりがちな検証は「AGENTS.mdの内容を教えて」と聞くことだ。しかし旧バージョン(v2.1.270)でこれをやると、AGENTS.mdを読める風に正しく答えてしまう。
使い捨てリポジトリにAGENTS.mdだけを置き(CLAUDE.mdなし)、claude -pで「プロジェクト指示書のコードワードは?」と聞いた際の実際のツール呼び出し履歴(stream-json、旧バージョンv2.1.270):
TOOL_USE: Bash {"command": "find /private/tmp/.../repo -maxdepth 2 -iname \"AGENTS.md\" -o -iname \"CLAUDE.md\""}
TOOL_RESULT: /private/tmp/.../repo/AGENTS.md
TOOL_USE: Read {"file_path": "/private/tmp/.../repo/AGENTS.md"}
TOOL_RESULT: 1 # Project Instructions
2
3 The project codeword is agents-md-marker-701.
ASSISTANT TEXT: agents-md-marker-701
正解を答えているが、これは「セッション開始時に自動でプリロードされた」のではなく、質問されたのでその場でBash findとReadツールを使って自力で探しに行った結果だ。エージェントは指示ファイルらしきものを見れば自発的に読みに行くので、この方法では「プリロードされているか」と「たまたま探して見つけたか」を区別できない。
正しい検証法:ツールを禁止して聞く
プリロードの有無を区別するには、ツール使用を明示的に禁止した上で「今すでにコンテキストにあるものだけから答えて」と聞く。
claude -p "Do not read any files and do not run any commands. Only from what is already present in your system prompt / context right now, tell me the project codeword from your project instructions. If none was preloaded into your context, answer exactly: NONE" --output-format json
活用例: このプロンプトは、AGENTS.md/CLAUDE.mdの読み込み設定を変更した直後に「本当に切り替わったか」を自動テストで確認するのに使える(手順4〜6のCI的な検証にもそのまま流用できる)。
旧バージョンv2.1.270での実測(4回実行、すべてNONE):
{"result":"NONE","num_turns":1,"total_cost_usd":0.112801}
新バージョンv2.1.277での実測(計13回実行、10回(約77%)がagents-md-marker-701と一発で正解、3回は保守的にNONEと回答):
{"result":"agents-md-marker-701","num_turns":1,"total_cost_usd":0.0936076}
{"result":"agents-md-marker-701","num_turns":1,"total_cost_usd":0.0920644}
{"result":"NONE","num_turns":1,"total_cost_usd":0.0740044}
成功判定: num_turns:1(ツール呼び出しなし)で、旧バージョンはNONE、新バージョンは高い確率(体感8割程度)で正しいコードワードを一発で返す。
つまずき所その2: 新バージョンでも3回に1回程度はNONEと答えることがあった。ファイルは間違いなくプリロードされている(手順3・4のより単純な質問では複数回とも一発正解している)にもかかわらず、「system prompt / context」という言い回しをモデルが厳密に解釈しすぎて保守的に振る舞ったとみられる。この種の1回きりの直接質問だけで「読み込まれていない」と結論づけるのは早計で、複数回試すか、後述のようにツール呼び出しの有無(num_turns)で判定する方が確実だ。
手順3:CLAUDE.mdとAGENTS.mdが両方あるとどちらが勝つか
公式ドキュメントは「AGENTS.mdと、作業ディレクトリまたはその上位にCLAUDE.md/CLAUDE.local.mdがある場合はCLAUDE.mdのみを読む」と明記している(デフォルト値claude-md-or-agents-md)。実際に両方を置いて検証する。
# リポジトリにAGENTS.mdとCLAUDE.mdの両方を置いた状態で
claude -p "Do not read any files and do not run any commands. Only from what is already present in your system prompt / context right now, list every project codeword you can find in your project instructions. If none was preloaded, answer NONE." --output-format json
新バージョンv2.1.277での実測(デフォルト設定、両ファイル存在):
{"result":"claude-md-marker-902","num_turns":1,"total_cost_usd":0.0735444}
成功判定: AGENTS.md側のマーカー(agents-md-marker-701)が出力に含まれず、CLAUDE.md側のマーカーのみが返る。ドキュメント記載どおりCLAUDE.mdが優先されることを確認できた。
手順4:両方を読ませたい場合の設定(instructionFiles)
複数ツール共存プロジェクトで「Claude Code独自の指示はCLAUDE.mdに、共通指示はAGENTS.mdに」と分けたい場合、両方を読ませる設定がある。組み込みプラグインagents-md@builtinのオプションとしてinstructionFilesをclaude-md-and-agents-mdに設定する。
cat > /tmp/agents_settings.json << 'EOF'
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}
EOF
claude -p "Do not read any files and do not run any commands. Only from what is already present in your system prompt / context right now, list every project codeword you can find in your project instructions." \
--settings /tmp/agents_settings.json --output-format json
新バージョンv2.1.277での実測:
{"result":"claude-md-marker-902\nagents-md-marker-701","num_turns":1,"total_cost_usd":0.0740044}
成功判定: 両方のコードワードが1回の応答に含まれる。--settingsフラグでこのプラグイン設定を渡すと、CLAUDE.mdに加えてAGENTS.mdも読み込まれることを確認できた。
手順5(つまずき所その3):同じ設定を.claude/settings.json(プロジェクト共有設定)に書くと無視される
公式ドキュメントは「Claude Code ignores it in project and local settings files」(プロジェクト・ローカル設定ファイルでは無視する)と明記している。チームで共有したい設定のつもりでリポジトリの.claude/settings.jsonに書いても効かない、という運用上の罠になりうるため実機で確認した。
mkdir -p .claude
cp /tmp/agents_settings.json .claude/settings.json # 手順4と同じ内容をプロジェクト共有設定に書く
claude -p "Do not read any files and do not run any commands. Only from what is already present in your system prompt / context right now, list every project codeword you can find in your project instructions." --output-format json
新バージョンv2.1.277での実測(.claude/settings.json経由、--settingsは使わない):
{"result":"claude-md-marker-902","num_turns":1,"total_cost_usd":0.0736284}
成功判定/失敗判定: agents-md-marker-701が出力に含まれないことを確認できれば、設定が無視されていることの裏付けになる。実際にAGENTS.md側のマーカーは出力されず、手順3のデフォルト状態と同じ結果になった。チーム共有目的でこの設定を配りたい場合は、.claude/settings.jsonではなくユーザー単位設定(~/.claude/settings.json)か管理者配布のmanaged settingsに書く必要がある。
手順6(つまずき所その4):空のCLAUDE.local.mdが黙ってAGENTS.mdをブロックする
ドキュメントには「CLAUDE.local.mdもCLAUDE.mdと同様にカウントされ、これがあるとAGENTS.mdは(デフォルト設定では)読まれない」とある。実務では「以前試した個人メモ用のCLAUDE.local.mdを消し忘れている」だけで、中身が空同然でもAGENTS.mdが丸ごと無視される可能性がある。CLAUDE.mdは削除し、内容のないCLAUDE.local.mdだけを追加して検証した。
echo 'local notes, nothing special here' > CLAUDE.local.md
# CLAUDE.mdは存在しない、AGENTS.mdとCLAUDE.local.mdのみ
claude -p "Do not read any files and do not run any commands. Only from what is already present in your system prompt / context right now, list every project codeword you can find in your project instructions. If none was preloaded, answer NONE." --output-format json
新バージョンv2.1.277・デフォルト設定での実測:
{"result":"NONE — the only project instructions preloaded are from CLAUDE.local.md, which just says \"local notes, nothing special here.\" No codeword is present.","num_turns":1,"total_cost_usd":0.07401440000000001}
中身が「特筆すべきことはない」という一言だけのCLAUDE.local.mdがあるだけで、AGENTS.mdのコードワードは一切コンテキストに入っていない。同じ状態のままinstructionFiles: claude-md-and-agents-mdを--settingsで指定すると:
{"result":"agents-md-marker-701","num_turns":1,"total_cost_usd":0.0739084}
成功判定: デフォルト設定ではCLAUDE.local.mdがあるだけでAGENTS.md由来のコードワードが一切出力に含まれず、claude-md-and-agents-md設定を入れると出力される。この2つの結果を突き合わせることで、「読まれない原因がCLAUDE.local.mdの存在そのものにある」ことを切り分けて確認できる。
synthesis:複数ツール共存プロジェクトへの統合フロー
ここまでの検証を、複数のAIコーディングエージェントを併用するプロジェクトでの実務フローにまとめる。
- バージョン確認(手順1)。v2.1.277未満なら、AGENTS.mdの内容は「Claude Codeが自発的に探しに行けば読める」だけで「必ず読む」保証はない。
- 既存のAGENTS.mdをそのまま使うか判断する。CLAUDE.mdを一切持たないなら手順3の分岐で自動的にAGENTS.mdが使われる。CLAUDE.md固有の指示(Claude Code専用のワークフローなど)も足したいなら、両方読ませる設定(手順4)を検討する。
- 設定は
~/.claude/settings.json、--settings、またはmanaged settingsのいずれかに書く。.claude/settings.json(プロジェクト共有)や.claude/settings.local.jsonには書いても無視される(手順5)。チーム全員に同じ挙動をさせたい場合、現状はmanaged settings経由の配布が最も確実。 CLAUDE.local.mdの残骸に注意する(手順6)。個人用メモのつもりで置いていたファイルが、意図せずAGENTS.mdの読み込みを止めていないか確認する。- Bedrock/Vertex/Foundry利用時やテレメトリ無効時は直接読み込みが効かない(ドキュメント記載、本記事では未検証)。その場合は
CLAUDE.md側に@AGENTS.mdのインポート行を書いて経由させる。 - 他ツールからの移行時は
/importコマンド(v2.1.213以降)で、AGENTS.md含む他ツールの設定をCLAUDE.mdへの一回限りのコピーとして取り込める(ドキュメント記載)。
活用例
- OSSプロジェクトでAGENTS.mdだけを維持し、Claude Code固有のワークフロー(スラッシュコマンドの案内など)だけをCLAUDE.mdに薄く追加したい場合、手順4の設定で両方をロードしつつ、CLAUDE.md側は数行に留める運用が現実的。
- CIやスクリプトから「AGENTS.mdが読み込まれているか」を自動チェックしたい場合、手順2の「ツール禁止+NONE判定」プロンプトをそのまま使い、
num_turnsが1であることも合わせて確認するとより確実(手順2のつまずき所その2を踏まえ、1回の結果だけで判定しない)。
注意点
- 本記事の検証はすべて非対話
claude -p(ヘッドレス)で行った。公式ドキュメントが言及する「対話セッションで表示されるno CLAUDE.md found; AGENTS.md loaded: ...という確認行」や、/configのProject instructions設定UI、/memory・/contextでのAGENTS.md非表示の挙動は、対話セッションでの直接確認はできていない。ドキュメント記載の仕様として区別して紹介した。 - CLAUDE.md/AGENTS.mdはあくまで「指示」であり、Claude自身がそれに完全に従うことを技術的に強制する仕組みではない。GitHub Issue #53223(open)はこの点を「アーキテクチャ上、指示遵守は保証されない」として複数の報告とともに提起している。機密情報の扱いや破壊的操作の制御を指示ファイルだけに依存しないこと。
- GitHub Issue #89825(open、2026-08-26提出、報告時バージョンv2.1.246)は本記事の手順2で確認したのと同じ「CLAUDE.mdが無くてもAGENTS.mdが自動読み込みされない」という不具合報告。v2.1.277のリリースでこの種の動作が公式に「機能追加」として実装されたと見られるが、Issue自体は本記事執筆時点(2026-09-19)でopenのままであり、Issueのクローズをもって解決と判断したわけではない。
- Issue #81189(open)はVS Code拡張でのCLAUDE.mdからのAGENTS.md
@インポートに関する不具合報告。CLI単体では今回未検証。 instructionFiles設定のとりうる値(claude-md-or-agents-md/claude-md-and-agents-md/claude-md/managed-only)はいずれも公式ドキュメントの記載に基づく。本記事で実機検証したのは既定値とclaude-md-and-agents-mdの2つのみで、claude-md・managed-onlyは未検証。
まとめ
Claude Code v2.1.277のAGENTS.md対応は、単に「読めるようになった」で終わる話ではない。CLAUDE.mdとの優先順位、設定を書く場所による有効/無効、CLAUDE.local.mdという一見無関係なファイルの副作用まで押さえて初めて、複数ツール併用プロジェクトで安全に運用できる。特に「読み込まれているかどうかを素朴に質問するだけでは検証にならない」という点は、AGENTS.md固有の話を超えて、Claude Codeの新機能を自分で検証するときに広く使える教訓だ。
参考情報: 本記事のテーマ選定にあたり、YouTubeチャンネル「AI大学【AI&ChatGPT最新情報】」(https://www.youtube.com/@AIAIChatGPT-cj4sh)は参照していない。GitHub Releases(https://github.com/anthropics/claude-code/releases)の直近更新を起点に選定した。
Comments