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

Claude Code を毎日使っているうちに、リポジトリのルートに CLAUDE.md と AGENTS.md の両方があるパターンが増えてきました。Cursor 時代の AGENTS.md がそのまま残っていたり、agents.md spec に乗っかって書いた AGENTS.md があったり。

両方ある状態で、こんな疑問が出てきます。

Claude Code はどっちを読んでいるんだろう？同じことを 2 箇所に書いていいの？片方を編集したら、もう片方も合わせるべき？

実はこの答えは Claude Code 公式 docs に 1 行で書かれていて、それを知らないままだと「同じ指示を 2 箇所に書いたのに食い違って動かない」という地味なハマり方をします。先に結論から。

先に結論

Claude Code は AGENTS.md を読みません。CLAUDE.md だけが、Claude Code を起動したタイミングで自動的に読み込まれます。

AGENTS.md を活かしたいなら、CLAUDE.md の冒頭に @AGENTS.md と書いて読み込ませる。これが Claude Code 公式 docs で明示的に推奨されているパターンで、個人開発モノレポでも一番素直に動く構成です。

本記事は、この結論に至るまでの仕様の読み解き、どっちに何を書くかの判断軸、そして読者がよく抱える疑問を 1 つずつ章立てで答えていく構成です。Claude Code v2.x 系前提、Next.js + Supabase + Stripe で個人開発するエンジニアを読者像として想定しています（v2.1.59 で auto memory が別系統として追加されましたが、本記事は CLAUDE.md / AGENTS.md の話に絞ります）。

こんな状態で詰まりやすい

たとえばこんな心当たりはないでしょうか。

• 公式 docs に「CLAUDE.md は読まれる」と書いてあったので CLAUDE.md だけ整備した。AGENTS.md の挙動は読み飛ばしていた（実は明記されている）
• Cursor / Codex と Claude Code を併用したくて両方を置いたら、同じことを 2 箇所に書く羽目になった
• サブディレクトリに CLAUDE.md を置いたのに、Claude が起動直後に書いた指示が効かない
• CLAUDE.md がいつの間にか 200 行を超えて、何を書いても効きが悪くなってきた気がする

全部、Claude Code がどのファイルをどのタイミングで読むかの挙動を 1 度押さえれば消えるモヤモヤです。順に答えていきます。

AGENTS.md と CLAUDE.md は何が違う？

ざっくり言うと、AGENTS.md は「全 AI ツール共通の指示書」、CLAUDE.md は「Claude Code 専用の指示書」。同じ「AI への指示書」でも、対象が違います。

AGENTS.md の役割

AGENTS.md は agents.md コミュニティ仕様 に乗っかった、AI コーディングエージェント全般に向けた共通の指示書です。Cursor / Codex / Cline といった複数のツールが「リポジトリに AGENTS.md があれば読む」前提で設計されています。中身はどのツールでも通じるプロジェクト前提 — 技術スタック、ディレクトリ構造、命名規則、ビルドコマンドなど。

CLAUDE.md の役割

CLAUDE.md は Anthropic 公式の Claude Code 専用 ファイルです。Claude Code を起動したときに自動的に読み込まれて、会話のコンテキストに注入されます。中身は Claude 固有の運用ルール（plan mode を使う条件、特定ディレクトリの hook、auto memory との連携など）に向いています。

ここで一番ハマるポイントは次の 1 行に集約されます。

「Claude Code reads CLAUDE.md, not AGENTS.md.」 （Claude Code は CLAUDE.md を読みます。AGENTS.md は読みません）

公式 docs の AGENTS.md セクションに明記されています。Claude Code は AGENTS.md を直接読まない。これを知らないまま両方書いていると、「片方の指示だけが効いて、もう片方は無視されている」という現象が起きます。

5 軸で並べると違いがくっきりする

役割の違いを 5 つの観点で並べると、輪郭がはっきりします。

スコープ欄が CLAUDE.md だけ細かいですが、これには理由があります。CLAUDE.md は Anthropic 公式仕様で 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 しか使わないなら、CLAUDE.md だけで足りる？

足ります。 AGENTS.md は他の AI ツール（Cursor / Codex / Cline 等）と併用するときに意味があるファイルなので、Claude Code 単独運用なら作る必要はありません。

むしろ Claude Code 単独運用なら CLAUDE.md 一本に絞る方がパワフルです。@import 構文（他ファイルを取り込める）や 4 階層スコープ（managed / project / user / local）といった Claude 固有機能は CLAUDE.md でしか使えません。AGENTS.md には階層概念も import 構文もないので、複数ツール併用の予定がないうちから AGENTS.md に分散させるのは持ち損になります。

別のツールも併用する流れになってから AGENTS.md を切り出して @AGENTS.md import に切り替えるのが、無駄が出ない順序です。

どっちに何を書く？ 迷った時の判断フロー

新しい指示やルールを書こうとした時、どっちのファイルに書けばいいか。次のフローを上から順に当てはめれば 3 ステップ以内で決まります。

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 と CLAUDE.md の重複、どう避ける？

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 という構文で、相対パスも絶対パスも書けます。最大 5 階層まで再帰的に展開されるので、@AGENTS.md が @docs/conventions.md を import している、みたいな構成も組めます。

Claude は起動時に AGENTS.md の中身を読み込んで、その後 CLAUDE.md の Claude 固有ルールを追記する形でコンテキストに展開します。

これで「AGENTS.md は Cursor / Codex 等が読む。Claude Code は CLAUDE.md 経由で同じ AGENTS.md を読む」という二刀流が、内容の重複なしで成り立ちます。片方を更新すれば全 AI ツールに反映される運用です。

シンボリックリンクで CLAUDE.md → AGENTS.md にしてもいい？

import 以外にも、コミュニティで広く使われているパターンとしてシンボリックリンクがあります。ln -s AGENTS.md CLAUDE.md で 1 ファイル / 2 ファイル名の構成が作れて、Claude Code は symlink を透過的に処理するのでそのまま動きます。

@AGENTS.md import との使い分けはこんな感じ。

Claude Code 固有の挙動を活かしたいなら import 方式の方が柔軟です。Claude 固有ルールが要らないシンプルな運用なら symlink の方が管理が楽。

CLAUDE.md と CLAUDE.local.md はどう使い分ける？

CLAUDE.md は 4 階層あると書きましたが、その中で個人開発で一番使うのが「Project」と「Local」の使い分けです。

• CLAUDE.md（Project）: チーム共有、git 管理対象。チーム全員が必要な前提・ルール
• CLAUDE.local.md（Local）: 個人専用、.gitignore 推奨。自分だけのテストデータ、sandbox URL、個人の好みのルール

衝突した場合は、同じディレクトリ内なら CLAUDE.local.md が後勝ち（CLAUDE.md の後に追加される形でコンテキストに入る）。/init の personal オプションを選ぶと CLAUDE.local.md を作ってくれて、自動で .gitignore に追加されます。

個人開発でも「自分用テスト URL」「Stripe テストキーの場所メモ」みたいなものは CLAUDE.local.md に分けておくと、共同作業者がいないうちから習慣にしやすいです。

モノレポでの使い分け 実例

筆者の個人開発モノレポは 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 階層制限の範囲内）。これで STRATEGY.md の更新が全リポの Claude Code に自動で反映されるので、戦略変更のたびに各リポの CLAUDE.md を編集する手間が消えました。

CLAUDE.md が長くなりすぎた時の対処は？

公式は CLAUDE.md を 200 行以下 にすることを推奨しています。200 行を超えると、Claude のコンテキスト枠を食いすぎて、結果的に「指示通りに動く度合い」が落ちます（公式は adherence と表現）。

ただし 200 行は厳守ではなく目安。超えても動きますが、何を書いても効きが悪く感じる時はだいたい行数オーバーが原因です。

対処は 2 通り。

• .claude/rules/ に分割する: paths フィールドで適用範囲を絞った path-scoped rule にする。特定のディレクトリのファイルを Claude が開いたタイミングで読み込まれる仕組みなので、常駐コンテキストを節約できる
• @path import で別ファイルに切り出す: 整理には効くけど、import したファイルも結局起動時に展開されるので、コンテキスト圧迫の解決にはならない（純粋に「読みやすく整理する」目的）

たとえば API ハンドラーを書くときだけ読み込ませたいルールは：

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

# API Development Rules

- All API endpoints must include input validation

src/api/ 配下のファイルを Claude が開いたときだけ、このルールが追加で読み込まれます。

サブディレクトリの CLAUDE.md はいつ読まれる？

ルートの CLAUDE.md は起動時にすぐ読まれますが、サブディレクトリの CLAUDE.md は そのサブディレクトリ配下のファイルを Claude が実際に開いたタイミング で読み込まれます。公式仕様の引用：

"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." （Claude は作業ディレクトリ配下のサブディレクトリにある CLAUDE.md / CLAUDE.local.md も発見します。ただし起動時にまとめて読み込むのではなく、Claude がそのサブディレクトリのファイルを開いたタイミングで読み込まれます）

つまり src/billing/CLAUDE.md は Claude Code を起動した瞬間には読まれません。Claude が src/billing/ 配下のファイルを実際に触りに行ったときに、初めて読み込まれます。「会話の最初から効かせたい指示」をサブディレクトリの CLAUDE.md に書くと、肝心の場面で間に合わないわけです。

ルールは単純です。「会話の最初から効かせたい全体方針」はルートの CLAUDE.md に。「そのサブディレクトリでだけ意識してほしいルール」（build コマンド、凍結ステータスなど）はサブディレクトリの CLAUDE.md に。役割を分けると、スコープ設計がスッキリします。

複数チームの monorepo で関係ない CLAUDE.md まで読まれて困る場合は、.claude/settings.local.json の claudeMdExcludes で除外できます。

同じことを 2 箇所に書いたら、どう優先される？

CLAUDE.md は階層的に複数置けます。じゃあ、ルートとサブディレクトリで違うことを書いていたらどうなるか。公式 docs にハッキリ書かれています。

"if two rules contradict each other, Claude may pick one arbitrarily." （2 つのルールが矛盾していると、Claude はどちらかを成り行きで選ぶ可能性があります）

「成り行き」（arbitrary）です。明確な優先度ルールに依存する設計を組むと、たまに裏切られます。

実運用での整理はこうなります。

• 概念上の precedence は「Managed policy > Project > User > Local」（より specific が勝つ、というのが公式の建前）
• 実運用では「そもそも衝突を起こさない」が正解。矛盾した指示を 2 つ置いたら、結果は信頼できない

公式が推奨しているのも「定期的に CLAUDE.md / .claude/rules/ を見直して、矛盾する指示を消す」運用です。階層を増やすほど、整理整頓のコストも上がります。

CLAUDE.md を編集したら、いつ反映される？

CLAUDE.md は Claude Code を起動したタイミング で読み込まれます。新しいセッションを始めれば、最新版が自動で反映されます。

進行中のセッションに対しては即時反映されません。/clear で新しいセッションを開始するか、いったん exit して claude を再実行すれば確実です。

ちなみに /compact で会話を要約圧縮した時は、ルートの CLAUDE.md が自動的に再注入されます（公式仕様）。サブディレクトリの CLAUDE.md は再注入されないので、/compact 後にそのディレクトリのファイルを開き直すと再 load されます。

CLAUDE.md がちゃんと読まれているか確認するには？

Claude Code 内で /memory コマンドを実行すれば、現在 load されている CLAUDE.md / CLAUDE.local.md / rules ファイルの一覧が見えます。ここに表示されていないファイルは読まれていません。

「ルートの CLAUDE.md は出ているが、サブディレクトリの CLAUDE.md が出ていない」場合は、まだそのサブディレクトリのファイルを Claude が触っていないだけ、という可能性が高いです（前述の on-demand load のため）。

設定全体の確認には /status も便利。アクティブな settings、エラー、4 階層のどれが効いているかが一覧で見えます。

そのまま使える最小テンプレ

ここまでの内容を踏まえて、個人開発モノレポでそのままコピペで使えるミニマルなテンプレを置いておきます（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 つ

記事を読んだ後、5 分でできる手当てを 3 つだけ。

1. AGENTS.md の存在確認: 自分のリポに AGENTS.md があるなら、CLAUDE.md の冒頭に @AGENTS.md を 1 行追記する
2. CLAUDE.md の行数チェック: wc -l CLAUDE.md して 200 行を超えていたら、.claude/rules/ への分割を検討
3. サブディレクトリの CLAUDE.md を見直す: 会話の最初から効かせたい指示が紛れ込んでいたら、ルートの CLAUDE.md に移動

まとめ

• Claude Code は CLAUDE.md だけを読む。AGENTS.md は直接読まない
• AGENTS.md を活かすなら CLAUDE.md の冒頭に @AGENTS.md を書いて読み込ませる
• AGENTS.md = 全 AI ツール共通の前提、CLAUDE.md = Claude 固有の運用ルール
• CLAUDE.md は 200 行以下に保つ。超えたら .claude/rules/ で path-scoped rule に分割
• サブディレクトリの CLAUDE.md は 会話の最初には読まれない。そのディレクトリのファイルを使う直前に読み込まれる
• 階層内で指示が衝突すると、Claude は成り行きでどちらかを選ぶ。衝突を起こさない運用が前提

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