AGENTS.md vs CLAUDE.md 解説

問題: AGENTS.mdとCLAUDE.mdの両方を持つリポジトリを開きます。似ているように見えます。似たようなことが書かれています。Claude Codeがどちらを読むか、他のツールがどちらを読むか、そもそもなぜ2つのファイルが存在するのかわかりません。

手っ取り早い解決策: Claude CodeはCLAUDE.mdを読みます。他のすべての主要なAIツールはAGENTS.mdを読みます。Claude Codeだけを使うならCLAUDE.mdだけが必要です。チームで複数のツールを使うなら、シンリンク1つで両方のツールが同じファイルを読みます。

ln -s CLAUDE.md AGENTS.md

1つの真実の源。重複なし。

AGENTS.mdとは何か

AGENTS.mdはLinux FoundationとAgent Interoperability Initiative Foundation（AAIF）が公開したクロスツール標準です。目的はリポジトリを開いたときにどのAIコーディングツールでも読める単一のコンテキストファイルです。

2026年4月時点で18以上のツールがサポートしています。OpenAI Codex、Gemini CLI、Devin、Cursor、Windsurf、Continue、Amp、Warp、Gooseすべてがファイルを読みます。60,000以上のGitHubプロジェクトで使われています。

AAIFスペックはファイルのスキーマを定義します。allowed_tools、disallowed_tools、agent_instructions、output_format、environmentなどのフィールドです。各ツールは理解できるフィールドを読み、理解できないフィールドをスキップします。

Claude CodeはこれらのスキーマフィールドをすべてIgnoreします。settings.jsonに独自の権限システムを持っています。AGENTS.mdコンテンツを（インポート経由で）取得すると、散文形式の指示を読み、構造化フィールドを無視します。

CLAUDE.mdとは何か

CLAUDE.mdはClaude Codeのネイティブなコンテキストファイルです。すべてのセッションは会話の最初のトークンの前に読み込んで始まります。

このファイルはClaude Codeが読むためのドキュメントではありません。Claude Codeの実行方法のオペレーティングパラメーターです。ワークフロー、ルーティングロジック、品質ルール、デリゲーションパターンをここに入れます。プロジェクトのドキュメント、スタックのメモ、技術仕様はオンデマンドで読み込まれるスキルに属します。

目標サイズ: ソロセットアップで200〜500行。すべてのコントリビューターが内容を理解する必要がある共有チームファイルで50〜100行。

6レベルの優先度階層

Claude Codeは1つのファイルだけを読み込むのではありません。ファイルのスタックを読み込み、順序に従って解決します。内側が外側に勝ちます。

レベル1はグローバルデフォルトを設定します。レベル2はリポジトリルールを設定します。レベル3はラップトップから決して出てはいけないマシン固有のものを保持します。

CLAUDE.local.mdの落とし穴: Claude Codeはこのファイルを.gitignoreに自動的に追加しません。自分でやる必要があります。忘れると、gitがそれを追跡して次のコミットで上がります。ファイルの候補として良いもの: ローカルAPIエンドポイント、個人的なデバッグ設定、サンドボックスURL。これらはいずれも共有ツリーに属しません。

@importsとAGENTS.mdへのブリッジ

CLAUDE.mdファイル内で、@path/to/file.mdで別のファイルを取り込めます。インポートされたコンテンツは@行がある場所に注入されます。

これがClaude Code 2.1.59以降でAGENTS.mdをブリッジできる方法です。

# CLAUDE.md
@AGENTS.md
<!-- Claude reads AGENTS.md content here, but CLAUDE.md rules below take priority -->

## Claude-specific rules
- Use TodoWrite to track multi-step tasks
- Never use --dangerously-skip-permissions outside containers

インポートされたAGENTS.mdコンテンツが読み込まれます。しかし、レベル6（インポート）は階層で最も弱いレイヤーです。AGENTS.mdのルールがCLAUDE.mdに直接書かれたルールと衝突する場合、直接のルールが常に勝ちます。

これはAGENTS.mdコンテンツがインポート経由で取り込まれる場合、常にアドバイザリーであることを意味します。Claude Codeの動作を通知します。ルートファイルに書かれたものをオーバーライドしません。

シンリンクトリック

最もクリーンなマルチツールセットアップは、インポートの複雑さを完全に避けます。リポジトリルートで一度実行します。

ln -s CLAUDE.md AGENTS.md

これでAGENTS.mdはCLAUDE.mdを指すシンリンクになります。Claude CodeはCLAUDE.mdを読みます。Cursor、Windsurf、Gemini CLI、その他すべてのAGENTS.md対応ツールはAGENTS.mdを読みます。すべてが同じバイトを読みます。

重複なし。同期の問題なし。維持するファイルが1つ。

唯一のトレードオフ: Claude CodeはAGENTS.mdのスキーマフィールドを無視し、AGENTS.md対応ツールはClaude Code固有の指示（TodoWriteや--dangerously-skip-permissionsフラグなど）を無視します。実際にはそれで十分です。散文形式の指示は両方で機能します。スキーマフィールドは単にスキップされます。

自動メモリとMEMORY.md

Claude Code 2.1.59以降は、プロジェクトルートのMEMORY.mdファイルに自律的に書き込めます。このファイルはレベル5にあり、リポジトリレベルのCLAUDE.mdと同じ優先度です。

ファイルには厳格な制限があります。200行と25KB。オンデマンドのトピックファイル（memory/auth.mdやmemory/payments.mdなど）は、それぞれ最大120行です。MEMORY.md自体はそれらのトピックファイルを指すインデックスとして機能します。

注意すべき点: 互いに矛盾するメモリエントリはサイレントな曖昧さを引き起こします。Claude Codeはエラーをスローしません。単に2つの相反する指示を持ち、静かに解決します。それはあなたの期待通りにならないかもしれません。MEMORY.mdを定期的に監査してください。再発していない30日以上前のエントリを削除してください。

CLAUDE.mdが間違う7つの方法

ほとんどのチームはCLAUDE.mdを一度書いて再訪しません。これらは時間とともに蓄積する失敗モードです。

優先度の飽和: ALWAYSとNEVERとCRITICALラベルが多すぎる。すべてのルールが叫ぶとき、どれも届きません。Claude Codeは過負荷なファイルをすべてのルールに均等に注意を向けることで処理します。厳格な制約を最大5〜7に保ちましょう。

「関連するかもしれない」ラッパー: Claude Codeがセッションコンテキストを注入するとき、このヘッジでラップすることがあります。そのラッパーはコンテンツが読み込まれたが指示としてではなく背景として扱われていることを示します。このラッパーを持つファイルは厳密に従われていません。

インポート深度の希釈: インポートされたファイルの指示は直接書かれたものより弱いです。CLAUDE.md → @a.md → @b.mdのようなチェーンはb.mdに到達するまでに非常に希釈されます。重要なルールをルートファイルに保ちましょう。

トラウマの再生: MEMORY.mdはあなたがこれまで行ったすべての修正を蓄積します。50セッション後、Claude Codeは50の異なる過去の過ちを同時に避けようとしています。パフォーマンスが低下します。定期的な監査がこれを修正します。

バイアスの蓄積: メモリに書き込まれた肯定的な確認（「ユーザーはXを好む」）は、現在の好みに合わなくなったルールに固まる可能性があります。6ヶ月前に好んでいたものが今日好んでいるものではないかもしれません。

指示の遵守vs強制: CLAUDE.mdはリンターのように強制されるのではなく、コンテキストとして読み込まれます。「em-dashを使わない」というルールは依然として違反される可能性があります。ルールが重要なら、コンテキストだけに頼るのではなく、実際のツール（リントルール、フック、フォーマッター）と組み合わせましょう。

/compact後の消失: /compactを実行すると会話が要約されます。チャットにあったがCLAUDE.mdにない指示は要約後に残りません。永続的なルールをファイルに書きましょう。セッションのみに保存しないでください。

各ファイルに何を入れるか

AnthropicのBoris ChernyはターゲットをDirectlyに説明しています。CLAUDE.mdはすべてのセッションで持続する必要がある動作を保持すべきです。

CLAUDE.mdに入れるもの: オペレーショナルワークフロー、ルーティングロジック、品質基準、調整プロトコル、厳格な制約（最大5〜7）、デリゲーションパターン。

スキルに入れるもの（オンデマンドで読み込む）: 技術パターン、フレームワーク規約、プロジェクト固有のコンテキスト、アーキテクチャドキュメント、チームの慣習。

CLAUDE.mdに入れないもの: アーキテクチャドキュメント（コードから読む）、最近のgit履歴（git logを使う）、現在のPRステータス、デフォルトですべてのモデルが従うボイラープレート指示。

他で見つかる行数のアドバイスは60行未満に留めるとしています。それは間違いです。半分の時間しか必要でないプロジェクトのトリビア60行は、すべてのリクエストに適用されるユニバーサルなオペレーショナルルール300行より多くの有効なコンテキストを無駄にします。関連性がメトリクスであり、長さではありません。

セットアップの選択

3つのパターンがほとんどのユースケースをカバーします。

Claude Codeのみを使う場合は、単一のCLAUDE.mdを書いてAGENTS.mdを完全に無視してください。あなたにとってそれは存在しません。

チームが複数のツールを使うがClaude Codeが主要な場合は、シンリンクを使いましょう。1つのファイル、両方のファイル名、メンテナンスのオーバーヘッドなし。Claude Codeで機能するスタイルで書きましょう。他のツールは散文から何でも取得します。

Claude Codeを他のツールが維持するリポジトリ全体のAGENTS.mdと同期させる必要がある場合は、CLAUDE.md内で@AGENTS.mdインポートブリッジを使用してください。インポートされたコンテンツはアドバイザリーであることを覚えておいてください。Claude固有のオーバーライドをインポート行の下に書いてください。

2つのファイル、1つの明確なルール: ClaudeはCLAUDE.mdを読み、他の全員はAGENTS.mdを読み、シンリンクが最も速くそれらを同じにする方法です。

よくある質問

AGENTS.mdとは何ですか?

AGENTS.mdはLinux FoundationとAgent Interoperability Initiative Foundationが公開したオープン標準です。リポジトリを開いたときにどのAIコーディングツールでも読める単一のコンテキストファイルを定義します。18以上のツールがサポートしており、Cursor、Windsurf、Gemini CLI、Devin、OpenAI Codexが含まれます。60,000以上のオープンソースプロジェクトで使われています。

Claude CodeはAGENTS.mdを読みますか?

Claude CodeはAGENTS.mdをネイティブに読みません。代わりにCLAUDE.mdを読みます。CLAUDE.mdファイル内に@AGENTS.mdインポート行を使用してAGENTS.mdコンテンツをClaude Codeに取り込むか、シンリンクを使用して両方のファイル名を同じファイルに向けることができます。どちらのアプローチもClaude Codeが権威として扱うファイルを変えません。

AGENTS.mdとCLAUDE.mdの違いは何ですか?

AGENTS.mdはどのAIコーディングアシスタントでも読めるクロスツール標準です。CLAUDE.mdはClaude Codeのネイティブファイルで、すべてのセッションの開始時に自動的に読み込まれます。AGENTS.mdはallowed_toolsやoutput_formatなどのフィールドを持つ構造化スキーマを使用します。CLAUDE.mdは散文形式の指示を使用し、@imports、CLAUDE.local.md、自動メモリなどのClaude Code固有の機能をサポートします。

CLAUDE.mdには何を入れるべきですか?

すべてのセッションに適用されるオペレーショナルルール: ワークフロー、ルーティングロジック、品質基準、厳格な制約、デリゲーションパターン。厳格な制約は最大5〜7にしてください。アーキテクチャドキュメント、最近のgit履歴、デフォルトですべてのモデルが従うボイラープレート指示は入れないでください。技術仕様とプロジェクトコンテキストはオンデマンドで読み込まれるスキルに属し、ルートファイルには属しません。

CLAUDE.local.mdは何に使いますか?

CLAUDE.local.mdはバージョン管理にコミットすべきでないマシン固有の設定を保持します。良い候補: ローカルAPIエンドポイント、個人的なデバッグ設定、サンドボックスURL。Claude Codeは自動的に.gitignoreに追加しないため、自分でやる必要があります。忘れると、ファイルが次のコミットで上がり、すべてのコントリビューターにローカル設定が公開されます。

CLAUDE.mdとAGENTS.mdを一緒に使うにはどうすればよいですか?

最もクリーンなアプローチはリポジトリルートでのシンリンクです。ln -s CLAUDE.md AGENTS.md。Claude CodeはCLAUDE.mdを読み、他のすべてのツールはAGENTS.mdを読みます。両方が同じバイトを重複なしで読みます。Claude Codeをチームが維持する共有AGENTS.mdの下流に置く必要がある場合は、CLAUDE.mdの中で@AGENTS.mdインポートを使用してClaude固有のオーバーライドをインポート行の下に書いてください。