AGENTS.md vs CLAUDE.md｜Claude Code 設定ファイルの違いと使い分け 2026

結論を 1 行で

Claude Code は AGENTS.md を読まない。CLAUDE.md だけが session 開始時に自動で読み込まれる。 AGENTS.md を活かしたければ、CLAUDE.md の冒頭に @AGENTS.md と書いて import する。

これが Claude Code 公式 docs の挙動で、個人開発モノレポでもこのパターンが一番素直に動く。本記事ではこの結論に至るまでの仕様確認、判断フロー、そして自分のモノレポ 6 リポジトリでの実例を整理する。

この記事の前提

• 環境: Claude Code v2.x 系（v2.1.59 で auto memory が別系統として追加されたが、本記事は CLAUDE.md / AGENTS.md の話に絞る）
• 読者の状況: Next.js + Supabase + Stripe で個人開発するエンジニア、Claude Code を日常運用、AGENTS.md と CLAUDE.md のどちらに何を書くか迷っている
• 筆者の検証環境: モノレポ root + 5 サブプロジェクトで CLAUDE.md / AGENTS.md を併用運用中

この記事でわかること:

• AGENTS.md と CLAUDE.md の役割の違いを 1 行で説明できる
• どちらに何を書くかの判断フロー
• @AGENTS.md import で重複を避けるパターン
• サブディレクトリの CLAUDE.md がいつ読まれるかのスコープ設計
• 個人開発モノレポ向けの最小テンプレ

読者のよくある詰まり

• 公式 docs に「CLAUDE.md は読まれる」と書いてあるが、AGENTS.md は読まれるのか書いてないように見えた（実は明記されている）
• 別の AI ツール（Cursor / Codex 等）と Claude Code を併用したい時、リポに AGENTS.md と CLAUDE.md の両方を置くと重複が出る
• サブディレクトリの CLAUDE.md がいつ読まれるのか分からず、書いた指示が効かない
• 200 行を超えた CLAUDE.md が長くなりすぎて、何を書いても効きが悪くなった気がする

これらは全部「読み込み挙動を 1 度キチンと押さえれば消える」モヤモヤだ。

それぞれの役割

AGENTS.md とは

AGENTS.md は agents.md コミュニティ仕様 に基づく、AI コーディングエージェント共通の指示ファイル。Cursor / Codex / Cline など、複数のツールが「リポジトリに AGENTS.md があれば読む」という前提で設計されている。中身はツール非依存のプロジェクト前提（技術スタック、ディレクトリ構造、命名規則、ビルドコマンド等）。

CLAUDE.md とは

CLAUDE.md は Anthropic 公式の Claude Code 専用ファイル。Claude Code は session 開始時に CLAUDE.md を読み、コンテキストに注入する。中身は Claude 固有の運用ルール（plan mode 強制、特定ディレクトリの hook、auto memory との連携等）に向いている。

ここで一番大事な事実は次：

「Claude Code reads CLAUDE.md, not AGENTS.md.」

公式 docs の AGENTS.md セクションに 1 行で書かれている。Claude Code は AGENTS.md を直接読まない。これが分かっていないと「両方書いたのに片方しか効かない」現象に詰まる。

5 軸比較表

公式 docs では CLAUDE.md の置き場所が 4 階層に整理されている：

• Managed policy（組織管理）: /Library/Application Support/ClaudeCode/CLAUDE.md 等
• Project（チーム共有、git 管理対象）: ./CLAUDE.md または ./.claude/CLAUDE.md
• User（個人、全プロジェクト適用）: ~/.claude/CLAUDE.md
• Local（個人、特定プロジェクトのみ、.gitignore 推奨）: ./CLAUDE.local.md

AGENTS.md にはこの 4 階層の概念はない。基本的にプロジェクトルートに 1 つだけ置く想定。

どちらに何を書くか — 判断フロー

Claude Code 個人開発で迷ったら以下のフローで決める：

1. その情報は「全 AI エージェント共通の前提」か？
   → YES → AGENTS.md（CLAUDE.md は @AGENTS.md で import）
   → NO  → 2 へ

2. その情報は「Claude Code 固有の運用ルール」か？
   → YES → CLAUDE.md（Claude のみ参照）
   → NO  → 3 へ

3. その情報は「ローカル個人専用」か？
   → YES → CLAUDE.local.md（gitignore に追加）
   → NO  → 1 に戻って前提を再考

AGENTS.md に書く内容（推奨）

• リポの技術スタック（Next.js 16、Supabase、Stripe）
• ディレクトリ構造とファイルマップ
• 命名規則・コーディング規約
• node_modules/next/dist/docs/ を参照せよ等の ツール非依存の前提
• ビルド・テストコマンド

CLAUDE.md に書く内容（推奨）

• Claude の起動フロー（最初に何を読むか）
• 凍結プロジェクト一覧などの 会話文脈ルール
• plan mode を使う条件
• git push の deny / allow ルール
• subagent / hook の使い分け

重複を避ける @AGENTS.md import パターン

AGENTS.md と CLAUDE.md を両方使うとき、同じ内容を 2 箇所に書くと食い違いやすい。公式が推奨するのは CLAUDE.md の冒頭で AGENTS.md を import するパターン：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

@path/to/file 構文は relative / absolute 両対応で、最大 5 hops まで再帰的に展開される。Claude が session 開始時に AGENTS.md の中身を読み込み、その後 CLAUDE.md の Claude 固有ルールを追記する形でコンテキストに入る。

これで「AGENTS.md は Cursor も読む / Claude Code は CLAUDE.md 経由で同じ内容を読む」の二刀流が成り立つ。

ケーススタディ: モノレポ 6 リポジトリでの実例

筆者の個人開発モノレポは root + 5 サブプロジェクトの構成で、それぞれ AGENTS.md / CLAUDE.md を使い分けている。

@AGENTS.md

# masatoman.net（アフィリエイトブログ）

## ターゲット
「Claude Code で個人開発を月¥5万にする本業エンジニア」
...

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file
structure may all differ from your training data. Read the relevant
guide in `node_modules/next/dist/docs/` before writing any code.
Heed deprecation notices.

recipe-ai/CLAUDE.md も同パターン。冒頭で @AGENTS.md、続いて凍結ステータス（2026-04-29 凍結確定）と Phase 1/2 ルールを記述している。AGENTS.md 側にはアーキテクチャ・ファイルマップ・台所ループのデータフロー等、ツール非依存の前提が入っている。

monorepo root の CLAUDE.md はさらに 1 段深く @../STRATEGY.md で戦略ドキュメントを import している（5 hops 制限の範囲内）。これにより STRATEGY.md の更新が全リポの Claude Code session に反映される。

ハマりどころ 3 つ（公式仕様の理解で消える）

1. AGENTS.md だけ書いて「Claude Code が指示通り動かない」

公式が明確に書いている通り、Claude Code は AGENTS.md を直接読まない。AGENTS.md だけ整備しても Claude Code には何も伝わっていない。CLAUDE.md を作って @AGENTS.md を 1 行入れるだけで解決する。

2. CLAUDE.md が肥大化して指示が効かなくなった

公式は CLAUDE.md を 200 行以下 にすることを推奨している。200 行を超えると context window を消費しすぎて adherence（指示への従順度）が落ちる。対処は 2 つ：

• .claude/rules/ ディレクトリに分割し、paths frontmatter で path-scoped rule にする（特定ディレクトリのファイルを開いた時だけ load される）
• @path import で別ファイルに切り出す（ただし import したファイルも launch 時に展開されるので、context 削減には繋がらない、整理目的）

例えば API ハンドラーを書くときだけ load したいルールは：

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation

3. サブディレクトリ CLAUDE.md は on-demand load

公式仕様：

"Claude also discovers CLAUDE.md and CLAUDE.local.md files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories."

つまり src/billing/CLAUDE.md は session 開始時には読まれない。Claude が src/billing/ 配下のファイルを開いた時に初めて load される。「session の最初から効かせたい指示」をサブディレクトリの CLAUDE.md に書くと、その指示はそのディレクトリのファイルを開くまで効かない。

session の最初から効かせたい全体方針はルートの CLAUDE.md に。サブディレクトリ固有の build / 凍結ステータス等はサブディレクトリの CLAUDE.md に。これを意識するだけでスコープ設計が綺麗になる。

衝突した時の挙動

CLAUDE.md は階層的に複数置けるが、内容が衝突した場合の挙動は公式 docs に明記されている：

"if two rules contradict each other, Claude may pick one arbitrarily."

つまり「ルートと subdirectory で違うことを書いていたら、Claude はどちらかを arbitrary に選ぶ」。明確な優先度ルールに依存する設計をすると裏切られる。

設計上の整理は次が安全：

• 概念上の precedence は「Managed policy > Project > User > Local」（より specific が勝つ）
• 実運用では「衝突を起こさない」が正解。衝突したら Claude の判断は arbitrary

定期的に CLAUDE.md / .claude/rules/ を見直して、矛盾する指示を消す運用が公式推奨。

個人開発モノレポ向けテンプレ

そのまま使える最小テンプレ（Next.js + Supabase 想定）：

AGENTS.md:

# このリポについて

Next.js 16 (App Router) + Supabase + Stripe の個人開発プロジェクト。

## 技術スタック
- Next.js 16 (App Router) + TypeScript
- Supabase (Auth, DB, RLS)
- Stripe (決済)
- Tailwind CSS

## 重要ルール
- Next.js 16 は破壊的変更あり。コード書く前に
  `node_modules/next/dist/docs/` を確認
- Supabase クライアントは `lib/supabase/` の既存ユーティリティを使う
  （新規作成しない）

## コマンド
- `npm run dev` — 開発サーバー
- `npm run build` — 本番ビルド
- `npm test` — Vitest

CLAUDE.md:

@AGENTS.md

## Claude Code 運用ルール

- 3 ステップ以上のタスクは plan mode で開始
- コードを読まずに書かない（探索 → 絞り込み → 実装の順）
- 動作を証明できるまで完了とマークしない
- 最小差分で解決。リファクタ・横展開は別タスクに
- 不確実なら止まってユーザーに確認

## 起動フロー（指示なしで会話開始時）
1. `STATUS.md` を読んで残タスクを把握
2. ユーザー指示があればそれに従う
3. なければ依存なしの最上位タスクを 1 つ提案

このセットだけで、Cursor / Codex / Claude Code すべてが「Next.js 16 の破壊的変更に注意」を共有しつつ、Claude Code だけが追加の運用ルールを読む構成になる。

今日やること（3 つ以内）

1. AGENTS.md の存在確認: あるなら CLAUDE.md の冒頭に @AGENTS.md を追記
2. CLAUDE.md の行数チェック: 200 行超なら .claude/rules/ 分割を検討
3. サブディレクトリ CLAUDE.md の見直し: session 起動時に効かせたい指示はルートに移動

関連記事

まとめ

• Claude Code は CLAUDE.md だけを読む。AGENTS.md は直接読まない
• AGENTS.md を活かすなら CLAUDE.md の冒頭で @AGENTS.md import
• AGENTS.md = ツール非依存の前提、CLAUDE.md = Claude 固有の運用ルール
• CLAUDE.md は 200 行以下、超えるなら .claude/rules/ で path-scoped rule
• サブディレクトリの CLAUDE.md は on-demand load（session 起動時には読まれない）
• 階層内で内容が衝突したら Claude は arbitrary に選ぶ → 衝突を起こさない運用が前提

Claude Code の設定ファイルを「とりあえず置いてある」状態から「読み込み挙動を理解した上で配置する」状態にすると、Claude が指示通り動く割合が一段上がる。次は subagent や hook で運用を自走させる フェーズに入っていける。