ついにClaude CodeがAGENTS.mdに対応──CLAUDE.mdとの優先順位・併用設定を公式実装から読み解く

Claude Code が、ついに AGENTS.md に対応しました。

これまで Claude Code では、プロジェクト固有の指示を書くファイルとして CLAUDE.md が使われてきました。一方、OpenAI Codex をはじめとする複数の AI コーディングエージェントでは AGENTS.md が使われており、両方を併用するプロジェクトでは AGENTS.md と CLAUDE.md をそれぞれ管理する必要がありました。

しかし Claude Code 2.1.277 で状況が変わります。Claude Code 自身が AGENTS.md をプロジェクト指示として扱えるようになりました。

ただし「Claude Code が CLAUDE.md をやめて AGENTS.md へ移行した」という理解は正確ではありません。重要なのは、CLAUDE.md と AGENTS.md をどう使い分けるかを選択できるようになったという点です。

この記事では、Anthropic の公式実装をもとに、両者の優先関係・併用方法・ネストしたファイルの扱い、そして現時点で残っている差分まで整理します。

この記事の要点

• デフォルトは「CLAUDE.md があればそれを使い、なければ AGENTS.md にフォールバック」
• 両方読ませたいなら claude-md-and-agents-md への変更が必要
• AGENTS.md と CLAUDE.md は「ほぼ同じ」だが「完全に同じ」ではない

対象読者

• Claude Code と Codex など、複数の AI コーディングエージェントを併用している方
• CLAUDE.md と AGENTS.md の二重管理に疲れている方
• モノレポで指示ファイルを分割管理したい方

検証環境

項目	バージョン
Claude Code	2.1.277
設定箇所	/config → Project instructions
実装	組み込み mod agents-md

Claude Code 2.1.277 で AGENTS.md をサポート

Claude Code 2.1.277 で AGENTS.md サポートが追加されました。リリース内容では次の動作が追加されています。

プロジェクトに CLAUDE.md が存在しない場合、Claude Code は代わりに AGENTS.md を読む

読み込み方法は /config に追加された Project instructions から変更できます。実装は Anthropic 公式リポジトリの mods/agents-md から確認できます。

この機能は 2.1.277 時点で Amazon Bedrock / Google Vertex AI / Microsoft Foundry 経由では未対応です。クラウドプロバイダ経由で Claude Code を運用しているチームは、まだ CLAUDE.md 前提の構成を維持してください。

結論：デフォルトは「CLAUDE.md → なければ AGENTS.md」

今回の仕様で最も重要なのがここです。Claude Code のデフォルト設定は claude-md-or-agents-md です。

名前の通り、次のフォールバック方式になります。

つまり、こういう構成だった場合、

project/
├── CLAUDE.md
└── AGENTS.md

デフォルトでは CLAUDE.md だけがプロジェクト指示として使われ、AGENTS.md は追加で読み込まれません。

ここは「両方読み、競合したら CLAUDE.md が勝つ」という仕様ではありません。プロジェクト固有の CLAUDE.md が存在すれば、AGENTS.md へのフォールバック自体が発生しないという設計です。

「CLAUDE.md がある」の判定範囲

地味ですが重要な点です。この判定は、リポジトリルートから作業ディレクトリまでのパス上にある以下のファイルを見ます。

• CLAUDE.md
• .claude/CLAUDE.md
• CLAUDE.local.md

これらが 1 つでもあれば、プロジェクト全体がエンジン側の管轄になり、agents-md は関与しません。

逆に、以下は**「プロジェクト固有の CLAUDE.md」としてカウントされません**。

• 組織が配布する managed ファイル
• ユーザー個人の ~/.claude/CLAUDE.md
• .claude/rules 配下のファイル
• --add-dir で追加したディレクトリの CLAUDE.md

「グローバルに ~/.claude/CLAUDE.md を置いているから AGENTS.md は読まれないはず」というのは誤解です。読まれます。

両方読ませたい場合：claude-md-and-agents-md

Claude Code には、そのための設定も用意されています。/config を開き、Project instructions を claude-md-and-agents-md に変更します。

このモードでは、次の両方が Claude Code のコンテキストに入ります。

project/
├── CLAUDE.md   ← 読まれる
└── AGENTS.md   ← 読まれる

Project instructions には 4 つのモードがある

公式実装では、Project instructions に 4 種類のモードが用意されています。

モード	動作
claude-md	CLAUDE.md のみ使用
claude-md-or-agents-md	CLAUDE.md がなければ AGENTS.md を使用（デフォルト）
claude-md-and-agents-md	CLAUDE.md と AGENTS.md の両方を使用
managed-only	プロジェクトや個人の指示を除外し、組織管理の指示などを残す

通常の個人開発・チーム開発で重要になるのは、上 3 つでしょう。

settings.json から設定することもできる

/config だけでなく、設定ファイルからも指定できます。両方を読み込む場合は、ユーザー設定 ~/.claude/settings.json などで次のように書きます。

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}

このプラグインオプションは、プロジェクト側の .claude/settings.json では設定できません。ユーザー設定・--settings・managed settings のいずれかで指定します。チーム全体に強制したい場合は managed settings を使うことになります。

このオプションは当初 projectInstructions というキー名でした。旧キーの値も当面は解釈され、それぞれ次のモードにマップされます。

旧 (projectInstructions)	新 (instructionFiles)
claude	claude-md
agents-fallback	claude-md-or-agents-md
both	claude-md-and-agents-md
none	managed-only

なお、セッション開始時のトランスクリプトに「どう読み込まれたか」が記録されるので、意図通りに効いているかはそこで確認できます。

AGENTS.md と CLAUDE.md はどう使い分けるべきか

ここからが今回の変更で面白いところです。複数の AI コーディングエージェントを利用する場合、次のような役割分担が可能になります。

AGENTS.md：エージェント共通のルール

# Project Instructions

## Build

npm run build

## Test

npm test

## Coding Rules

- TypeScriptを使用する
- public APIにはテストを書く
- lintエラーを残さない

CLAUDE.md：Claude Code 固有の指示

# Claude Code Instructions

- 大規模変更の前にPlanを作成する
- Claude Code固有のSkillsを必要に応じて利用する
- 作業終了前にテスト結果を確認する

概念的には、こういう分離になります。

複数エージェントを使う開発環境では、かなり合理的な構成です。

落とし穴：両方置くだけでは両方読まれない

ここは注意が必要です。前述の通り、Claude Code のデフォルトは claude-md-or-agents-md です。

そのため、

project/
├── AGENTS.md
└── CLAUDE.md

と配置しただけでは、Claude Code は CLAUDE.md しか読みません。共通指示を AGENTS.md、Claude 固有指示を CLAUDE.md に分けるのであれば、claude-md-and-agents-md への変更が必須です。

今回のアップデートで最も間違えやすいのがここです。

AGENTS.md だけに統一する選択肢も現実的になった

逆に、AGENTS.md だけにすることもできます。

project/
└── AGENTS.md

デフォルトの claude-md-or-agents-md では、CLAUDE.md がなければ Claude Code は AGENTS.md を読みます。そのため Codex・Claude Code・その他の対応エージェントで共通のプロジェクト指示を使うなら、AGENTS.md を Single Source of Truth にする設計が可能になりました。

これまでありがちだった「2 つのファイルにほぼ同じ内容を書く」運用を減らせます。地味ですが、かなり重要です。指示ファイルが複数存在すると、次のような Instruction Drift が起こり得るからです。

ネストした AGENTS.md にも対応している

さらに重要なのが、ルートの AGENTS.md だけではない点です。

project/
├── AGENTS.md
├── ios/
│   └── AGENTS.md
└── backend/
    └── AGENTS.md

ルートにはプロジェクト全体のルール、ios/ には iOS 固有ルール、backend/ にはバックエンド固有ルールを配置できます。agents-md 実装は、こうしたネストされた AGENTS.md も扱います。

たとえば ios/ 配下のテキストファイルを Claude Code が Read すると、そのディレクトリ階層に対応する AGENTS.md が必要に応じてコンテキストへ追加されます。ただしそのディレクトリに CLAUDE.md があれば、そちらが優先されます。

なお、<dir>/AGENTS.md だけでなく <dir>/.claude/AGENTS.md も対象です。

大規模なモノレポでは、責務ごとに指示を分割できるようになります。

ただし、CLAUDE.md と完全に同じ挙動ではない

ここも重要です。AGENTS.md がサポートされたからといって、両者が完全に同じになったわけではありません。Anthropic 自身が公式実装の中で、ローディングにまだ差があることを説明しています。

たとえばネストした AGENTS.md は、現在の実装では主にテキストファイルへの Read に応じて追加されます。一方、Claude Code 本体の CLAUDE.md ローダーには、それ以外のコンテキスト経路もあります。

そのため現時点では、

AGENTS.md ≒ CLAUDE.md
AGENTS.md ≠ CLAUDE.md（完全一致ではない）

という状態です。この差は今後のアップデートで変わる可能性があるため、最新の公式実装を確認するのが安全です。

なぜ今回の変更は重要なのか

今回のアップデートは、単に「読める Markdown ファイルが 1 種類増えた」という話ではありません。

複数の AI コーディングエージェントを使う環境では、これまでツールごとに指示ファイルを管理する必要がありました。

しかし Claude Code が AGENTS.md に対応したことで、共通化が現実的になりました。

そして Claude Code 固有の指示が必要な場合だけ、AGENTS.md + CLAUDE.md の構成を取る。つまり、共通指示とツール固有指示を分離できるということです。

私ならどう構成するか

複数の AI コーディングエージェントを使うプロジェクトなら、次の構成が扱いやすいと考えます。

ファイル	役割
AGENTS.md	エージェント共通のプロジェクトルール
CLAUDE.md	Claude Code でのみ必要な指示

設定は claude-md-and-agents-md にします。

一方、Claude Code 固有の指示が特に必要ないのであれば、AGENTS.md だけを置き、デフォルトの claude-md-or-agents-md をそのまま使う。この方が指示の重複を避けられます。

まとめ

AGENTS.md 対応によって、AI コーディングエージェントの指示ファイル設計はかなり整理しやすくなりました。関係を整理すると次の通りです。

状況	挙動・設定
CLAUDE.md がある	デフォルトでは CLAUDE.md を使用
CLAUDE.md がない	AGENTS.md を使用
両方使いたい	claude-md-and-agents-md に変更

今回のアップデートは「CLAUDE.md が AGENTS.md に置き換わった」のではなく、**「Claude Code でも AGENTS.md を共通のプロジェクト指示として利用できるようになった」**と捉える方が正確です。

複数の AI コーディングエージェントを使う環境では、

AGENTS.md = 共通ルール
CLAUDE.md = Claude Code固有ルール

という分離が可能になります。あるいは Claude 固有の設定が不要なら、AGENTS.md だけを Single Source of Truth にすることもできます。

AI コーディング環境がマルチエージェント化していく中で、これは単なるファイル形式の追加ではなく、**「エージェントごとに指示を書く」から「プロジェクトとして共通の指示を持つ」**方向への重要な変化と言えそうです。

参考資料

• Claude Code Releases - Anthropic / GitHub
• Claude Code agents-md 公式実装 - Anthropic / GitHub
• AGENTS.md native support Feature Request - Anthropic / GitHub