Claude Code が AGENTS.md を読むようになった。ただしデフォルトはフォールバック

9 月 18 日にリリースされた Claude Code v2.1.277 には、AGENTS.md の機能リクエスト (#6235) が求めていた一行が入っていました。

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads
AGENTS.md instead; change it under "Project instructions" in /config
(not yet on Bedrock, Vertex or Foundry)

ほかのコーディングエージェント向けに用意されたリポジトリが、CLAUDE.md も import も hook もなしに Claude Code で動くようになりました。changelog のこの一行が語っていないのは、両方のファイルがある場合にどうなるか、そしてどのセッションではこの機能がそもそも使えないか、という点です。

Anthropic は具体的に何を出したのか？

四つの値を持つ設定と、両方ではなく片方のファイルを選ぶデフォルトです。デフォルトの claude-md-or-agents-md では、作業ディレクトリかその上位に CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md のどれかがあれば Claude は CLAUDE.md を読み、どれもなければ代わりに AGENTS.md を読みます。claude-md-and-agents-md は両方を読み、各ディレクトリで CLAUDE.md を先に読みます。claude-md は従来の動作に戻し、managed-only は起動時に組織の管理ファイルと自動メモリーだけを読み込みます。

~/.claude/CLAUDE.md、管理された CLAUDE.md、.claude/rules/ はこの判定に含まれないので、AGENTS.md と並んで引き続き読み込まれます。また、この設定はプロジェクト設定やローカル設定のファイルでは無視されます。置き場所はユーザー設定、--settings ファイル、管理ポリシーのいずれかです。クローンしたリポジトリが自分で両方読むモードに切り替えることはできません。

デフォルトはマージか、フォールバックか？

フォールバックです。8 月に、指示ファイルは断片化ではなくアドレッシングだと書きました。import はレイヤーを組み合わせ、フォールバックは一方のファイルを読んでもう一方を捨てます。デフォルトはプロジェクト層でまさにそれをしています。オペレーター層は残り、これは正しい判断ですが、CLAUDE.md と AGENTS.md のあいだではディスク上に何があるかがルールになります。

ここには、ドキュメント自身が指摘している鋭い落とし穴があります。CLAUDE.local.md も判定に含まれるのです。AGENTS.md を使うプロジェクトで、コミットしない個人用メモのために開発者が一人これを追加すると、その人の環境だけで Claude はチームの AGENTS.md を読まなくなります。エラーは出ません。プロジェクトは何も変わっておらず、変わったのは一人の開発者の gitignore されたファイルだけなのに、チームの指示がその一席から消えます。

両方読むモードでも解決しません。このモードは CLAUDE.md、AGENTS.md の順に連結するだけで、ドキュメントは別の箇所で競合について率直に書いています。二つのルールが矛盾すると、Claude はどちらを選ぶかわからない、と。コンテキストウィンドウ内の順序は優先順位ではありません。8 月の記事では、マージされたファイルにも一つだけルールがあると認めました。文書内の順序です。ドキュメントによれば、それすらありません。あの記事で残した問い、つまりどのファイルがなぜ勝つのかという問いは、今度は一段下で開いたままです。プロジェクトとオペレーターのあいだではなく、二つのプロジェクトファイルのあいだで。

黙って動かないのはどこか？

Anthropic から機能フラグを取得しないセッションすべてです。Amazon Bedrock、ほかのサードパーティープロバイダー、テレメトリーを無効にしたセッションが該当します。さらに、この機能を含むバージョンをインストールまたはアップグレードした直後の最初のセッション、disableAllHooks や allowManagedHooksOnly を使う構成、組み込みの agents-md プラグインが無効なセッションでも動きません。これらすべてで Claude は CLAUDE.md しか読まず、設定は /config に表示すらされません。

つまり同じリポジトリが、プロバイダー、テレメトリーの設定、新バージョンで最初のセッションかどうかによって、二人のチームメンバーに別々のプロジェクト指示を渡しうるということです。チームにとってはこれが changelog でいちばん重要な一文で、しかもその一文は changelog に書かれていません。

新しい信頼の穴が開くのか？

ほとんど開きません。リポジトリはもともと CLAUDE.md を同梱できたので、AGENTS.md がモデルに届いても新しい権限が生まれるわけではありません。AGENTS.md 内の外部 @path import は承認ダイアログすら出さず、そのプロジェクトで外部 import をすでに承認している場合にだけ読み込まれます。

変わるのは可視性です。デフォルトでは、AGENTS.md を読み込むと対話セッションに一行の通知が出ますが、このファイルは /memory にも /context の Memory files 一覧にも表示されず、InstructionsLoaded hook も発火しません。指示の監査をこの hook に頼っているなら、この読み込み経路はログに一切現れません。そもそも hook は観測するだけで読み込みを止められません。これはプロンプトは不変条件ではないと書いたときに引いた、ログとゲートの違いです。別のエージェント向けに書かれたリポジトリが、監査が見ていない唯一の経路を通って Claude に届くようになりました。自分のリポジトリにもちょうどそういうものがあります。「Codex Instructions」という見出しの AGENTS.md があり、CLAUDE.md はありません。このリポジトリは、対応するどのセッションでもフォールバックの対象になります。

複数のツールを使うチームはどうすべきか？

一行の import を残してください。次のような CLAUDE.md は

@AGENTS.md
 
## Claude Code
(Claude-specific lines go here)

プロジェクト指示が読み込まれる場所ならどこでも AGENTS.md を読み込みます。Bedrock やテレメトリー無効のセッションも含みます。/context に表示され、hook が有効なら InstructionsLoaded を発火させ、Claude だけに向けた行を書く余地も残ります。ドキュメントでも、この import を残しておけば、どの設定でも Claude が AGENTS.md を二重に読むことはないと確認されています。制約が一つあります。import が読み込むのは名前を指定したファイルだけです。CLAUDE.md が存在すると、デフォルトはサブディレクトリの AGENTS.md も探さなくなるので、ネストした AGENTS.md には隣に専用の CLAUDE.md import を置くか、両方読む設定が必要です。ネイティブのフォールバックは、リポジトリを一度だけ開く人にとっては良いデフォルトです。毎日そこで作業する人にとっては、たまたまどのファイルがあるかで決まるルールより、明示的な参照のほうが今も優れています。