AGENTS.mdとCLAUDE.mdを両方置くとどちらが勝つか──公式ドキュメントの答えは「そもそも読まれない」だった

結論から書く。AGENTS.mdとCLAUDE.mdを同じリポジトリに両方置いても、Claude Codeの中で「優先順位の勝負」は起きない。Claude Codeは初期状態でAGENTS.mdというファイルの存在を一切認識しないからだ。読むのはCLAUDE.mdだけ、というのが公式ドキュメントの明文である。つまり質問の立て方そのものがずれていて、正しくは「どちらが勝つか」ではなく「AGENTS.mdの内容をCLAUDE.md側に橋渡しする方法はあるか」になる。以下、公式ドキュメント（code.claude.com、2026年8月27日にcurlで取得・確認）の原文を根拠に、この橋渡しの仕様と、実務で引っかかる点を書く。

• Claude CodeはCLAUDE.mdだけを読み、AGENTS.mdは読まない。両者が競合して優先順位が決まる場面はそもそも存在せず、共存させる公式手段は「@AGENTS.mdインポート」と「シンボリックリンクln -s AGENTS.md CLAUDE.md」の2つだけ。
• Windowsではシンボリックリンク作成に管理者権限かDeveloper Modeが要るため、公式は@AGENTS.mdインポートを代替として明記している。
• /initがAGENTS.mdを自動で読み込む条件は、日本語版ドキュメントと英語版ドキュメントで記述が食い違っている（英語版はCLAUDE_CODE_NEW_INIT=1が必要と明記、日本語版はその条件に触れていない）。他ツール設定をまとめて取り込む/importコマンド自体、2026年8月27日時点の日本語版commands.mdには記載を見つけられなかった。

読まれないなら「優先順位」という概念自体が存在しない

公式ドキュメント「Claude があなたのプロジェクトを記憶する方法」のAGENTS.md節は、この一文から始まる。

Claude Code は CLAUDE.md を読みます。AGENTS.md ではありません。リポジトリが既に他のコーディングエージェント用に AGENTS.md を使用している場合、CLAUDE.md を作成してそれをインポートし、両方のツールが重複なしに同じ指示を読むようにします。

英語版原文も併記しておく。

Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents, create a CLAUDE.md that imports it so both tools read the same instructions without duplicating them.

「両方使っている場合にどちらが優先か」という設計にはなっていない。CodexやCursorなど他のエージェント向けにAGENTS.mdを既に置いているリポジトリで、Claude Code用に何もしなければ、Claude CodeはそのAGENTS.mdの存在ごと無視してCLAUDE.mdだけを見る（CLAUDE.mdが無ければ、指示は何も読み込まれない）。「優先順位を調べたい」という動機の裏には、両方に書いた指示が食い違って実際にどちらが効いているか分からない状況があるはずだが、答えは「AGENTS.md側は最初から効いていない」で決着する。

公式が用意している共存手段は2つだけ

重複なしに両ツールへ同じ指示を配るための方法として、公式は次の2つを挙げている。

方法1: @AGENTS.mdインポート。 CLAUDE.mdの先頭でAGENTS.mdをインポートし、その下にClaude Code固有の指示を足す。

@AGENTS.md

## Claude Code

`src/billing/` の下の変更には Plan Mode を使用します。

公式によれば「Claude はインポートされたファイルをセッション開始時に読み込み、その後残りを追加します」。つまりAGENTS.mdの内容が先、Claude Code専用の追記が後、という順番でコンテキストに入る。

方法2: シンボリックリンク。 Claude Code専用の追記が不要なら、CLAUDE.md自体をAGENTS.mdへのシンボリックリンクにしてしまう。

ln -s AGENTS.md CLAUDE.md

英語版ドキュメントにはこのコマンドの後に一文追加されている。

The command prints no output on success. In your next session, run /context and confirm CLAUDE.md appears under Memory files.

成功時は無出力のため、貼った直後は何も起きたように見えない。次のセッションで/contextを実行し、Memory filesの欄にCLAUDE.mdが出ているかで確認しろ、という指示だ。なお、この一文は日本語版memory.mdには存在しない。ja版は同じ例示コードの直後、確認手順に触れずそのままWindowsの注意書きに移っている。翻訳漏れか意図的な省略かは記載から判断できず、「日本語版に無い」という事実だけを述べる。

Windowsについては両言語版とも同じ内容が書かれている。

On Windows, creating a symlink requires Administrator privileges or Developer Mode, so use the @AGENTS.md import instead.

管理者権限もDeveloper Modeも使いたくないWindows環境では、素直に@AGENTS.mdインポートを使えばよい。

/initと/import──ここでドキュメントの日本語版と英語版が食い違う

AGENTS.mdを既に持つリポジトリで/initを実行したときの挙動について、日本語版と英語版で記述が一致しない。まず日本語版memory.mdの該当箇所。

既に AGENTS.md を持つリポジトリで /init を実行すると、それを読み込み、関連する部分を生成された CLAUDE.md に組み込みます。また、.cursorrules、.devin/rules/、.windsurfrules などの他のツール設定も読み込みます。

これだけ読むと、/initを素朴に実行すればAGENTS.mdは無条件で取り込まれるように見える。ところが英語版memory.mdの同じ箇所はこうなっている。

Running /init reads Cursor rules, in .cursor/rules/ or .cursorrules, and Copilot rules, in .github/copilot-instructions.md, and incorporates the relevant parts into the generated CLAUDE.md. With CLAUDE_CODE_NEW_INIT=1 set, /init also reads AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules.

英語版では、素の/initが無条件で読むのはCursorルールとCopilotルールだけで、AGENTS.mdを読むのは環境変数CLAUDE_CODE_NEW_INIT=1を設定した場合に限る、と明記されている。日本語版にはこの条件が書かれていない。どちらが実際の挙動を正しく反映しているかは、本記事の執筆時点（2026年8月27日）で実機検証しておらず断定できない。少なくとも言えるのは、日本語版ドキュメントを額面通り信じて「/initだけでAGENTS.mdは自動で拾われる」と判断するのはリスクがあるということだ。フラグを立てずに試して反映されなければ、CLAUDE_CODE_NEW_INIT=1を設定してから/initをやり直す、という手順を踏む必要がある。

さらに、他のコーディングエージェントの設定を取り込む専用コマンド/importが英語版commands.mdには存在する。

/import [codex|gemini] [--dry-run] [--yes] — Bring configuration from other coding agents on your machine, currently OpenAI Codex and Google Gemini CLI, into Claude Code, including instruction files, MCP servers, commands, subagents, and skills. [...] Not available on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, or Claude Platform on AWS. [...] Requires Claude Code v2.1.213 or later

対応するのはOpenAI CodexとGoogle Gemini CLIの2つで、Codexの設定ファイルはAGENTS.mdなので、/import codex経由でAGENTS.mdの内容がCLAUDE.mdへ一度だけコピーされる（@インポートと違い、以後は同期されない）。Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundry、AWS上のClaude Platformでは使えず、v2.1.213以降が必要、という制限も明記されている。

ところが日本語版commands.mdをcurlで取得して/importを検索しても、この行そのものが見当たらない。日本語版のコマンド表に載っているのは/initだけだった。翻訳が追いついていないのか生成元のバージョンが古いのかは分からないが、2026年8月27日時点の日本語版commands.mdには/importの記載が見つけられなかった。AGENTS.mdの扱いを日本語ドキュメントだけで把握しようとすると、この関連コマンドの存在自体を見落とす。

symlinkの向き、Windows、そしてExplore/Planエージェントの盲点

実際に運用する上で引っかかりそうな点を挙げる。

symlinkの向きはCLAUDE.md→AGENTS.mdの一方向。 公式のコマンドはln -s AGENTS.md CLAUDE.mdで、実体はAGENTS.mdのまま、CLAUDE.mdの方がリンクになる。逆向き(AGENTS.md側をリンクにする運用)は公式に例示がなく、他のエージェントがAGENTS.mdをシンボリックリンクとして解決できるかも記載がない。公式の例に沿い、実体はAGENTS.md、CLAUDE.mdはそこへのリンクという向きで統一するのが安全だ。

symlinkの成功確認は次セッションの/context頼み。 ln -sは成功時に無出力なので、貼った直後は効いているか画面上で確認できない。次セッションで/contextを実行しMemory files欄を見るほか、「設定をデバッグする」ページによれば/memoryコマンドでも読み込まれたCLAUDE.mdとルールファイル、オートメモリのエントリを一覧できる。symlink運用に切り替えた直後は、この2つのコマンドで中身が読めているか確認してから使い始めるべきだ。

組み込みのExplore/PlanエージェントはCLAUDE.mdそのものをスキップする。 「設定をデバッグする」ページのトラブルシューティング表にこうある。

組み込みの Explore および Plan エージェントは CLAUDE.md をスキップします。カスタムサブエージェントはメイン会話と同じ方法で読み込みます

つまり@AGENTS.mdインポートやsymlinkでCLAUDE.mdにAGENTS.mdの内容を橋渡ししても、組み込みのExplore/Planエージェントに処理を委譲した瞬間、その指示ごと読まれなくなる。効かせたいなら委譲プロンプトに直接書き直すしかない、と同じページが案内している。カスタムサブエージェント(自分で定義したエージェント)はメイン会話と同じ読み込み方なので影響を受けない。

プロジェクト直下の@AGENTS.mdは「外部インポート」の承認ダイアログには通常引っかからない。 英語版memory.mdの警告文で、外部インポートは「パスが作業ディレクトリの外に解決される場合」と定義されている（日本語版の同箇所には、この定義文自体がなく承認ダイアログの挙動のみが書かれている）。プロジェクトルート同士の@AGENTS.mdは作業ディレクトリの内側に解決されるため、この定義に沿えば初回承認ダイアログの対象にはならないはずだ。ただしこれはダイアログの発火条件からの読み取りであり、AGENTS.mdインポートに固有の記述として明記されているわけではない。

公式ドキュメントで確認できなかったこと

以下は、curlで取得した範囲の公式ドキュメント（memory.md、commands.md、debug-your-config.mdの日英版など）を検索しても記載を見つけられなかった事項。推測では埋めない。

• サブディレクトリにAGENTS.mdだけが置かれ、CLAUDE.mdが存在しないケースでの挙動。CLAUDE.mdのサブディレクトリ読み込みはオンデマンドと明記されているが、AGENTS.md単独配置についての言及はなかった。
• @AGENTS.mdでインポートした内容と、CLAUDE.md本体の追記が矛盾した場合にどちらが優先されるかの明示。CLAUDE.md内での「後に書かれたものが最後に読まれる」という一般則から類推はできるが、AGENTS.mdインポートに固有の優先規則としては書かれていない。
• /initのAGENTS.md読み込み条件について、日本語版・英語版のどちらの記述が実際の挙動と一致するか。本記事執筆時点では実機での再現確認をしていない。
• claude.ai(Web版)やClaude Agent SDK側でAGENTS.mdに関する扱いがあるかどうか。今回確認したのはcode.claude.com配下のClaude Code向けドキュメントのみで、Agent SDK関連ページは対象にしていない。
• シンボリックリンクされたCLAUDE.mdをリポジトリごと共有し、異なるOSでチェックアウトした場合の挙動。

CLAUDE.md自体の書き方（何を書けば守られるか、200行の目安、hookとの役割分担など）は別記事「CLAUDE.mdに何を書くと守られ、何を書いても守られないのか」で扱っているので、AGENTS.mdとの共存設定を終えたあとの中身の書き方はそちらを参照してほしい。

Claude Code公式ドキュメントを日本語版・英語版で確認

• Claude があなたのプロジェクトを記憶する方法（日本語版） https://code.claude.com/docs/ja/memory
• How Claude remembers your project（英語版） https://code.claude.com/docs/en/memory
• コマンド（日本語版） https://code.claude.com/docs/ja/commands
• Commands（英語版） https://code.claude.com/docs/en/commands
• 設定をデバッグする（日本語版） https://code.claude.com/docs/ja/debug-your-config

（いずれも2026年8月27日にcurlで生Markdown（URL末尾.md）を取得し、原文を確認した上で引用している。）