Claude Code は AGENTS.md をサポートしているか？ 完全リファレンス 2026

Claude Code が本格普及して以降、よく聞かれる質問がある：Claude Code は AGENTS.md をサポートしているか？ OpenAI Codex や Cursor で AGENTS.md を既に使っているチームなら、当然1ファイルで運用したい。期待される答えは「Yes」だが、実際の答えはもう少し複雑だ。

Claude Code は AGENTS.md を直接読み込まない。 これは Anthropic 公式ドキュメント (2026年5月版) に明示されている：「Claude Code reads CLAUDE.md, not AGENTS.md.」

この記事では：

• Claude Code がなぜ AGENTS.md を直接読まないのか
• Anthropic が推奨する3つの公式統合パターン
• AGENTS.md が既に存在する状態での /init の挙動
• Windows 固有の symlink 注意点
• 両方のファイルをメンテナンスするチームが知るべきこと

を解説する。

公式の見解

code.claude.com/docs/en/memory (2026年5月版) より引用:

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.

Claude Code の立場は明確：CLAUDE.md をエントリポイントに保ちつつ、AGENTS.md をその中に取り込む。以下の3つのメカニズムは、すべてこの設計を維持しながら、AGENTS.md を「ツール横断指示の単一の真実の出所」として保持する。

なぜ AGENTS.md を直接読まないのか

Anthropic の設計理由（ドキュメントの文脈と設計判断から推測）:

1. 後方互換性 — CLAUDE.md は AGENTS.md がツール横断標準になる前に導入された。既存ユーザーが CLAUDE.md をリポジトリに commit している。
2. Claude 固有の拡張機能 — Claude Code は @import、claudeMdExcludes、.claude/rules/ の path-scoped rules など、AGENTS.md 仕様にない機能をサポート。
3. 階層的セマンティクス — Claude Code は祖先ディレクトリから CLAUDE.md を読み込む（親 → カレント → サブディレクトリ）。AGENTS.md のフラットな発見ロジックより複雑。
4. Auto memory との連携 — Claude Code の auto memory は ~/.claude/projects/<project>/memory/ に書き込まれ、CLAUDE.md の loading order と相互作用する。

AGENTS.md を CLAUDE.md と同じように扱わせると、AGENTS.md 仕様を他ツール向けに壊すか、Claude Code の loading セマンティクスを分断することになる。

統合パターン1: @-syntax で AGENTS.md を import

これが Anthropic 推奨パターン。AGENTS.md を信頼の出所にしつつ、Claude 固有の拡張が必要な場合に最適。

# CLAUDE.md

@AGENTS.md

## Claude Code 拡張

- `src/billing/` 配下の変更は plan モードを使う
- `prod/**` への commit 前に `npm run test:integration` を実行
- Subagent: `code-reviewer` は PR 生成時に自動実行

動作:

1. Claude Code がセッションを開始 → CLAUDE.md を読み込み
2. @AGENTS.md ディレクティブが AGENTS.md の内容をインライン展開
3. Claude 固有の指示がその下に続く

@import を初回検出した時、Claude は対象ファイルのリストを承認ダイアログで表示する。一度承認すると、以降のセッションは静かに読み込む。

最大 import 深度: 5 hops。AGENTS.md 自身が他のファイルを @ で import 可能だが、チェーンは 5 段で上限。

パス解決: import は import を含むファイルを基準に解決される（作業ディレクトリ基準ではない）。CLAUDE.md 内の @AGENTS.md は ./AGENTS.md (CLAUDE.md と同じ階層) を指す。

統合パターン2: Symlink（Unix系のみ）

Claude 固有の拡張が不要なら、symlink がシンプル：

ln -s AGENTS.md CLAUDE.md

これで Claude Code は CLAUDE.md という symlink 経由で AGENTS.md を読み込む。重複なし、@import 管理なし。

トレードオフ: symlink の下に Claude 固有のコンテンツを追加できない（ファイル自体が AGENTS.md なので）。後で Claude 固有の拡張が必要になったら、symlink を通常ファイルに変換して @AGENTS.md import に切り替える必要がある。

Windows での注意

Windows では symlink 作成に 管理者権限または Developer Mode が必要。OSが混在しているチームの場合：

• Linux/macOS の開発者: symlink で動く
• Windows の開発者: チェックアウト時にエラーまたは警告

クロスプラットフォームチームへの推奨: Pattern 1 (@AGENTS.md import) を使う。全OSで同じように動く。

統合パターン3: 両ファイルを独立してメンテナンス

最大の柔軟性が必要なチームでは、CLAUDE.md と AGENTS.md を別ファイルとして、内容を重複させつつメンテナンスする。

project-root/
├── AGENTS.md       # Codex, Cursor, 他ツール向け
└── CLAUDE.md       # Claude Code 向け、共通ルールは重複

使い分けが妥当な場面:

• AGENTS.md のフォーマットを Claude 向けに変えたくない
• ファイルごとに異なる読み手がいる（AGENTS.md = Codex 文体、CLAUDE.md = Claude 文体）
• 各ファイルをメンテする組織が異なる

リスクが高い場面:

• ドリフト — 片方だけ更新されてエージェントの挙動が乖離
• 矛盾 — 両ファイルに矛盾するルールがあって出力が不整合

ほとんどのチームでは、パターン1 (@import) が安全なデフォルト。

AGENTS.md が既にある状態で /init を実行すると

AGENTS.md が既に存在するリポジトリで /init を実行すると、特別なフローが走る:

Running /init in a repo that already has an AGENTS.md reads it and incorporates the relevant parts into the generated CLAUDE.md. It also reads other tool configs like .cursorrules and .windsurfrules.

具体的に:

1. Claude が AGENTS.md を読む
2. .cursorrules と .windsurfrules も読む
3. それらの関連部分を統合した CLAUDE.md を生成
4. ユーザーが内容をレビュー → commit

これが移行のための「スマート変換」パス。AGENTS.md ベースのリポジトリを Claude Code 対応にするとき、/init が CLAUDE.md の妥当なスタート地点を作る重労働を肩代わりしてくれる。

CLAUDE_CODE_NEW_INIT=1 環境変数を設定すると、対話型マルチフェーズフローに切り替わる:

• どのアーティファクトをセットアップするか（CLAUDE.md, skills, hooks）
• AGENTS.md のどのセクションを Claude 固有 / 共通とするか
• @AGENTS.md import を使うか、独立した CLAUDE.md を生成するか

対話型フローが、既存 AGENTS.md リポジトリに Claude Code をブートストラップする最もきれいな方法。

サブディレクトリの CLAUDE.md / AGENTS.md は？

CLAUDE.md と AGENTS.md (CLAUDE.md 経由で @ import された場合) のどちらも、Claude Code のディレクトリ階層ルールに従う:

• 祖先ディレクトリ の CLAUDE.md は起動時にロード
• サブディレクトリ の CLAUDE.md は Claude がそのディレクトリのファイルを読むときオンデマンドロード

以下のような構成の場合:

monorepo/
├── CLAUDE.md       # 起動時にロード
├── AGENTS.md       # CLAUDE.md の @AGENTS.md 経由で import
└── packages/
    └── auth/
        ├── CLAUDE.md  # packages/auth/ のファイル読み込み時にロード
        └── AGENTS.md  # Claude Code は自動では読まない

packages/auth/CLAUDE.md 内で明示的に packages/auth/AGENTS.md を import する必要がある:

# packages/auth/CLAUDE.md

@AGENTS.md

## Auth 固有の Claude Code ルール

- このディレクトリでは必ず `bcrypt.hash` を使う（`crypto.scrypt` 禁止）
- 編集前に `npm run test:auth` を実行

claudeMdExcludes 設定

モノレポで複数チームが並行作業する場合、claudeMdExcludes で特定の CLAUDE.md を除外できる:

{
  "claudeMdExcludes": [
    "**/other-team/CLAUDE.md",
    "/home/user/monorepo/legacy/.claude/rules/**"
  ]
}

これは AGENTS.md には直接効かない（Claude Code は AGENTS.md を直接読まないので）。ただし、他チームの CLAUDE.md が彼らの AGENTS.md を import してる場合、親 CLAUDE.md を除外することでその AGENTS.md も実質的に除外される。

移行戦略

AGENTS.md のみ → Claude Code 対応へ

# 案A: Symlink (Unix only、Claude 固有拡張なし)
ln -s AGENTS.md CLAUDE.md

# 案B: Import (クロスプラットフォーム、拡張可能)
echo "@AGENTS.md" > CLAUDE.md
# Claude 固有ルールを下に追加

CLAUDE.md のみ → マルチエージェント対応へ

# 共有内容を AGENTS.md に移動
mv CLAUDE.md AGENTS.md

# AGENTS.md を import する新しい CLAUDE.md を作成
echo "@AGENTS.md" > CLAUDE.md

# Claude 固有ルールを import 行の下に追加

既存 CLAUDE.md を AGENTS.md + Claude 固有拡張に分割

# 元の CLAUDE.md
## プロジェクトアーキテクチャ
[共有内容]

## コーディング規約
[共有内容]

## Claude Code Hooks
[Claude 固有]

## Subagent 権限
[Claude 固有]

を以下に分割:

# AGENTS.md (Codex, Cursor 等と共有)
## プロジェクトアーキテクチャ
[共有内容]

## コーディング規約
[共有内容]

# CLAUDE.md (Claude Code 固有)
@AGENTS.md

## Claude Code Hooks
[Claude 固有]

## Subagent 権限
[Claude 固有]

エッジケース

AGENTS.md が予期しないヘッダー/構文を使っていたら？

AGENTS.md 仕様には markdown 構文の制限がなく、Claude Code は柔軟に markdown を読む。コンテンツが有効な markdown である限り、Claude は問題なくロードする。実用上の問題は トークン消費 のみ — 過剰に長い AGENTS.md は遵守率を下げる。可能なら両ファイル合計で 200 行以下に。

AGENTS.md が @-syntax で他ファイルを import できる？

@import 構文は Claude 固有の拡張。CLAUDE.md 経由で import された AGENTS.md では @import が動く（Claude Code が再帰的に展開するため）。しかし Codex や Cursor が直接 AGENTS.md を読むと、@import は文字通りのテキストとして扱われる可能性が高い。

最大のクロスツール互換性のため、AGENTS.md 内では @import を避けて、import は全て CLAUDE.md に集約するのが推奨。

CLAUDE.local.md と AGENTS.local.md は？

CLAUDE.local.md は Claude 固有の拡張で、個人設定用（gitignored）。標準仕様には AGENTS.local.md はない。Claude 固有の個人設定には CLAUDE.local.md を使う、あるいはユーザーレベルルール用に ~/.claude/CLAUDE.md を活用する。

ツール別 AGENTS.md サポート比較表

Claude Code は 唯一明示的なブリッジファイル (CLAUDE.md) を必要とする主要エージェント。これは CLAUDE.md の専用機能を保つための意図的な設計。

関連記事

• AGENTS.md vs CLAUDE.md 徹底比較
• AGENTS.md × GitHub Copilot 完全ガイド
• AGENTS.md for OpenAI Codex 完全ガイド
• Caveman.MD 完全ガイド — AGENTS.md トークン圧縮プロトコル
• Claude Code Plugins 完全リファレンス 2026

FAQ

Claude Code は AGENTS.md をネイティブにサポートしているか？

いいえ。Claude Code は CLAUDE.md を読み、AGENTS.md は読まない。Claude Code で AGENTS.md の内容を使うには、@AGENTS.md syntax で CLAUDE.md に import するか、symlink (ln -s AGENTS.md CLAUDE.md、Unix のみ) を作る。

なぜ Claude Code は AGENTS.md を直接読まないのか？

Anthropic の設計は CLAUDE.md をエントリポイントに保つことで、後方互換性、Claude 固有機能（auto memory, path-scoped rules, claudeMdExcludes）、AGENTS.md のフラットな発見と異なる階層的 loading セマンティクスを維持する。

AGENTS.md が存在する状態で /init を実行すると？

/init は AGENTS.md と、存在すれば .cursorrules と .windsurfrules も読み込み、それらの関連部分を統合した CLAUDE.md を生成する。CLAUDE_CODE_NEW_INIT=1 を設定すると対話型フローで共有 vs Claude 固有の分割をガイドしてくれる。

Windows で symlink は使える？

可能だが、管理者権限または Developer Mode が必要。クロスプラットフォームチームでは @AGENTS.md import を使う方が安全 — 全OSで同じように動く。

@import の最大深度は？

5 hops。AGENTS.md 自身が @ で他ファイルを import 可能だが、チェーンは 5 段で上限。

AGENTS.md で @import 構文を使うべきか？

クロスツール互換性のため避けるべき。Codex や Cursor は @import を文字通りのテキストとして扱う可能性が高い。import は全て CLAUDE.md に集約し、CLAUDE.md が AGENTS.md を import する（AGENTS.md 自身は @import を持たない）構造が推奨。

claudeMdExcludes は AGENTS.md に効くか？

直接は効かない。ただし AGENTS.md を import している CLAUDE.md が除外されると、チェーン全体（AGENTS.md 含む）がスキップされる。

AGENTS.md がサブディレクトリにある場合は？

サブディレクトリの CLAUDE.md はオンデマンドで読み込まれる。各サブディレクトリの CLAUDE.md は、必要なら同階層の AGENTS.md を明示的に import する: @AGENTS.md。