AGENTS.mdとは何で、なぜこのファイルが存在するのですか？
AGENTS.mdは、単一のプロジェクト説明ファイルを複数のAIコーディングツールで共有できるようにすることを目的とした、クロスツールのプロジェクト指示ファイル仕様だ。各ツールがフォーマットの異なるほぼ重複した内容の設定ファイルを個別に維持する必要をなくす。The Registerの報道によると、この仕様はもともとOpenAI陣営が主に推進していたもので、Anthropicが2026年9月18日のv2.1.277でClaude Codeにもこれをサポートさせると決めたことは、実質的にCLAUDE.md、AGENTS.md、.cursorrulesなどほぼ同一内容の指示ファイルがリポジトリに積み重なっているという実際の保守負担を認めたことになる。
v2.1.277より前、Claude CodeはCLAUDE.mdしか認識せず、AGENTS.mdを一切読まなかった——インポートやsymlinkが、当時その内容を機能させる唯一の回避策だった。それ以降、公式ドキュメントは「フォルダにCLAUDE.mdがない場合、ClaudeはAGENTS.mdを確認して使用する」と明確に記載しており、もはや回避策は不要だ。
リポジトリにCLAUDE.mdとAGENTS.mdの両方が存在する場合、実際にはどちらが読まれますか？
公式のデフォルトはclaude-md-or-agents-mdモードだ：現在のディレクトリまたはその上位のディレクトリにCLAUDE.md、.claude/CLAUDE.md、またはCLAUDE.local.mdのいずれかが存在する限り、Claude Codeはそれらのみを読み込み、AGENTS.mdを完全にスキップする。AGENTS.mdがフォールバックとして読み込まれるのは、ディレクトリツリー全体にCLAUDE.mdのいずれのバリアントも存在しない場合のみだ。これは設定で変更できる：claude-md-and-agents-mdは両方を同時に読み込む（CLAUDE.mdが優先、重複は除去）、claude-mdはAGENTS.mdを完全に無視する、managed-onlyは組織が管理するCLAUDE.mdのみに制限する。
ここで最も見落とされやすい点は：CLAUDE.local.md（開発者個人用でバージョン管理されない設定ファイル）は、「CLAUDE.mdが存在するか」の判定において、チーム共有のCLAUDE.mdと完全に同じ扱いを受けることだ。つまり、チームのリポジトリが元々AGENTS.mdのみを使用していても、ある開発者が自分の個人設定のためにCLAUDE.local.mdを作成すると、デフォルトモードでは、その開発者のClaude Codeは静かにチーム共有のAGENTS.mdの読み込みを停止する。このファイルを作成していない他の同僚は影響を受けない。
チームが既にAGENTS.mdを維持していて、2つの重複ファイルを維持せずにClaude Codeにその内容を読ませたい場合、最も手間のかからない方法は何ですか？
コミュニティが整理した運用ガイドには、v2.1.277以前の時代から有効な2つの方法が挙げられている：CLAUDE.mdファイルの先頭に@AGENTS.mdというインポート行を1行追加する方法で、Claude Codeはセッション起動時にインポートされた内容を読み込み、その後CLAUDE.md内のClaude専用の追加指示を読み続ける。もう一つは、CLAUDE.mdからAGENTS.mdへ直接symlinkを作成する方法だ。Windowsではsymlinkの作成に管理者権限または開発者モードが必要なため、クロスプラットフォームのチームでは@AGENTS.mdインポート方式の方が実用的だ。
また、既にAGENTS.mdがあるリポジトリで/initを実行すると、その内容を読み込んで自動生成されるCLAUDE.mdに統合する、一度限りの統合オプションも提供され、インポート行を手動で書く必要がない。
設定したのにClaude CodeがAGENTS.mdを読み込んでいないようです。どこから調査を始めればよいですか？
まずバージョンがv2.1.277（2026年9月18日）以降であることを確認する——この機能には明確な境界線があり、ネット上に出回っているチュートリアルは新旧が混在しているため、古いバージョンの説明に行き着きやすい。次に現在使用しているプラットフォームを確認する：この機能はまだBedrock、Vertex、Foundryには拡張されていない。また、feature-flagの権限がない、またはtelemetryを無効化しているセッションもAGENTS.mdを読み込めない。新規インストールしたClaude Codeでは、最初のセッションが完了するまでこの機能は有効にならない。
これらすべてを確認して問題がなければ、ディレクトリツリーの中に意図せずCLAUDE.local.mdが存在していないかを確認する——これは最もよく見落とされる原因だ。このファイルがあると、Claude Codeは「すでにCLAUDE.mdが存在する」と判定し、AGENTS.mdを完全にスキップしてしまう。このファイルは通常バージョン管理の記録に現れないため、調査の際に見落とされやすい。
コミュニティ記事が記録した実際のシナリオ：あるチームのリポジトリは元々、複数のツールで共有するAGENTS.mdのみを置いていた。ある開発者が自分のエディタの好み設定を保存するためにCLAUDE.local.mdを作成した。デフォルトモードでは、その開発者のClaude Codeはそれ以降、自分のローカルファイルだけを読み込み、チーム共有のAGENTS.mdを一切読まなくなった。一方、このファイルを作成していない他の同僚は通常通りAGENTS.mdを読み続けた。チームは全員が同じ指示で作業していると思い込んでいたが、その開発者の出力スタイルがチームの規約と食い違い始めたことで、ようやく原因が追跡された。
利点は、チームが複数のAIコーディングツールを使用している場合、クロスツールで共有する単一の指示ファイルを維持でき、重複保守の負担を取り除けることだ。ネイティブサポートにより、もはやインポートやsymlinkのような回避策も不要になる。代償は、その便利さと引き換えの複雑さだ——4つの読み込みモード、CLAUDE.local.mdの隠れた優先順位、そしてまだ全プラットフォームをカバーしていない制限は、チーム全体で実際に一度確認してからでないと安心して依存できず、設定しただけで何も考えずに使えるものではない。