CLAUDE.md 書き方ベストプラクティス｜設計パターン・300行ルール完全ガイド

結論から言うと、CLAUDE.md は「Claude がコードを読んでも推測できないこと」だけを、公式推奨の 200 行以内・コミュニティ最適の 60 行前後で書くのがベストプラクティスです。 よく見かける「300 行ルール」は Anthropic 公式の数字ではなく、HumanLayer 社発のコミュニティ基準で、300 行は事実上の上限ラインという位置づけです。

この記事では、Claude Code 公式ドキュメント（2026 年 4 月時点）と運用コミュニティの知見をもとに、CLAUDE.md の書き方・設計パターン・育て方を体系的に整理します。

この記事でわかること

• CLAUDE.md の役割と Claude がどう読み込むかの公式仕様
• 200 行・300 行ルールの出所と、現場での現実的な運用ライン
• 配置場所（4 階層スコープ）と優先順位
• 含めるべき内容／書くべきでない内容の明確な線引き
• プロジェクト規模別の設計パターン（小規模・中規模・大規模・モノレポ）
• @import と .claude/rules/ によるファイル分割のベストプラクティス
• 「ルールが守られない」失敗の根本原因と対策
• すぐ使える CLAUDE.md テンプレート（ミニマル・標準・大規模）
• 書いた後の「育て方」フレームワーク

誰向けの記事か

• Claude Code を導入したが、思ったように指示が通らず悩んでいる開発者
• チームで CLAUDE.md の運用ルールを整備したいテックリード／エンジニアリングマネージャ
• 肥大化した CLAUDE.md を分割・整理したいプロジェクトオーナー
• 他のエージェント（Cursor、Codex 等）と併用しており、AGENTS.md との整理をしたい方

CLAUDE.md とは：Claude Code が毎回読み込む永続コンテキスト

CLAUDE.md とは、Claude Code がすべてのセッション開始時に自動で読み込む Markdown 形式の指示ファイルです。公式ドキュメントでは次のように定義されています。

CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone.
— Claude Code Best Practices

重要なポイントは 3 つです。

1. 毎セッション全文がロードされる — そのぶんコンテキストウィンドウとトークンコストを消費する
2. システムプロンプトではなく「ユーザーメッセージ」として注入される — つまり強制力はなく、Claude にとっては「あなたからの最初の依頼」に近い扱い
3. コードから推測できないことを書くのが目的 — 言語の標準慣習や、見れば分かるディレクトリ構成を書いても効果は薄い

この「ユーザーメッセージとして注入される」という構造的事実は、後述する「ルールが守られない問題」を理解するうえで決定的に重要です。

なぜ CLAUDE.md が重要か

CLAUDE.md を書くと書かないでは、Claude Code の実用性が大きく変わります。

• 毎回同じ指示を書き直さずに済む — ビルドコマンドや規約を 1 回書けば永続化
• チーム全員で「Claude の振る舞い」を揃えられる — git 管理することで PR レビュー対象にできる
• Claude の推測ミスを未然に防げる — 非自明な環境固有ルール（ポート競合、独自テストランナーなど）を明示できる
• トークンを節約できる — プロジェクト規約を都度チャットで説明しなくて済む

一方で、肥大化した CLAUDE.md は逆効果になります。Anthropic 公式は次のように警告しています。

Bloated CLAUDE.md files cause Claude to ignore your actual instructions!

長すぎる CLAUDE.md ではルールが「ノイズ」の中に埋もれ、Claude が従わなくなります。つまり「書けば書くほど効く」ではなく、適切な粒度・文量・構造で書くことが成果に直結するということです。

200 行ルールと 300 行ルールの真相

CLAUDE.md の文量について、ネット上で流通している 2 つの数字があります。どちらも根拠がありますが、出所が違うので整理して覚えておくとよいでしょう。

公式は「200 行以内」

Anthropic 公式ドキュメント（メモリ仕様）は明確に 「1 ファイルあたり 200 行を目標に」 と書いています。

Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.

「300 行ルール」は HumanLayer 発のコミュニティ基準

一方、日本語圏で広まっている 「300 行を超えると Claude の挙動がクラッシュする」 という話は、HumanLayer 社のブログ記事 "Writing a good CLAUDE.md" が起点です。同社は自社の実運用から次の経験則を出しています。

• 最適は 60 行未満
• 150〜200 個程度の指示数が現行 LLM の遵守限界
• 300 行を超えると確実に遵守率が低下

3 階層で覚えると迷わない

以上を踏まえて、実務では次の 3 階層で判断すると整理しやすくなります。

公式は「各行について『これを削除したら Claude が間違いを犯すか？』と問い、No なら削除せよ」と具体的な剪定の指針も示しています。まずは 200 行を守り、できれば 100 行未満まで絞り込むのが現実的なゴールです。

配置場所と優先順位：4 階層のスコープ

CLAUDE.md は 4 つのスコープに配置でき、それぞれ用途が異なります。

優先順位と「連結」の仕組み

公式仕様では、優先順位はより具体的なものが優先（ローカル > プロジェクト > ユーザー > 管理ポリシー）です。ただし注意点が 2 つあります。

1. 「上書き」ではなく「全て連結」されてコンテキストに注入される
2. 親ディレクトリは launch 時に全て walk up して読み込まれる

つまりモノレポで /repo/CLAUDE.md と /repo/apps/web/CLAUDE.md が両方あれば、web ディレクトリで作業すると両方が連結されて注入されます。親子で役割を分け、親に共通ルール、子にプロジェクト固有ルールを置くのが基本設計です。

サブディレクトリ内の CLAUDE.md は on-demand

サブディレクトリ（たとえば src/api/CLAUDE.md）は、Claude がそのディレクトリのファイルを読んだタイミングで初めて注入されます。したがって、細かいドメインルールはサブディレクトリに配置することで、全体のトークン消費を抑えながら必要なときだけ適用できます。

含めるべき内容 / 含めるべきでない内容

CLAUDE.md に何を書くかは、「Claude がコードを読んで推測できないこと」という基準一本で決まります。

リンターで強制できるものは書かない

CLAUDE.md に書くべきでない典型例は、リンターやコンパイラで機械的に強制できるルールです。

• インデント幅・クォート種別 → ESLint / Biome / Prettier
• import 順 → 自動整形ツール
• 型チェック → TypeScript コンパイラ
• 命名規則の機械的な強制 → Linter ルール

CLAUDE.md は、LLM の判断が必要なルールだけに絞るのが鉄則です。機械が守れるものは機械に任せてください。

基本構造：WHAT / WHY / HOW の 3 層モデル

英語圏・日本語圏の主要な解説記事で共通して使われる設計モデルが「WHAT / WHY / HOW」の 3 層です。短い CLAUDE.md でもこの構造を意識すると、Claude が情報を整理しやすくなります。

重要なのは WHY を省かないことです。WHY がないと Claude は「なぜこのルールがあるか」を理解できず、似て非なるケースで誤った判断をします。1〜2 文で構いません。背景だけ書きましょう。

プロジェクト規模別の設計パターン

CLAUDE.md は「規模に応じて」構成を変えるのがベストプラクティスです。規模ごとに推奨される形を整理します。

小規模プロジェクト：まず 1 枚で

個人開発や小規模プロジェクトなら、ルート直下の CLAUDE.md 1 枚で十分です。WHAT / WHY / HOW を 30〜60 行に収めて、必要になったら追加するスタイルが最も運用コストが低くなります。

中規模：.claude/rules/ でドメイン別に分割

ファイル数が 100 を超えたあたりから、CLAUDE.md が肥大化しがちです。このタイミングで .claude/rules/ ディレクトリにドメイン別のルールを切り出すと効果的です。

your-project/
├── CLAUDE.md                     # プロジェクト全体（100 行程度）
└── .claude/
    └── rules/
        ├── code-style.md          # コードスタイル
        ├── testing.md             # テスト規約
        └── security.md            # セキュリティ要件

.claude/rules/*.md は再帰的に発見され、launch 時に自動で連結されます。つまり @import を書かなくても自動で読み込まれます。

大規模・モノレポ：paths: フロントマターで条件付きロード

500 ファイルを超える規模やモノレポでは、すべてのルールを毎回ロードするとコンテキストが圧迫されます。そこで使うのが paths: フロントマターです。

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

# API Development Rules
- All API endpoints must include input validation
- Use Zod for schema validation

このルールは Claude が src/api/ 以下のファイルを触ったときだけロードされます。ドメインごとに細かくスコープを切れば、巨大リポジトリでもトークン効率を保てます。

path-scoped rules の既知の制約

2026 年 4 月時点で、.claude/rules/ の paths: フロントマターには運用上注意すべき挙動があります（GitHub Issue #23478）。

• path-based ルールは Claude がファイルを Read したときだけ注入される
• Write / Create のときには自動注入されない

新規ファイル作成時に規約を適用したいケースでは、path-scoped ルールだけに頼らず、プロジェクトルートの CLAUDE.md にも最低限の指示を書いておくのが安全です。

@import による構造化

CLAUDE.md は @ 記法で他ファイルをインラインで取り込めます。これを使うと巨大な単一ファイルを避けつつ、必要な情報だけを参照できます。

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

仕様の要点は次の通りです。

• 相対パス・絶対パス・ホームディレクトリ記法（~/）すべて使用可
• インポート先がさらに別ファイルをインポート可能（最大 5 階層）
• 初回のみ承認ダイアログが表示され、拒否すると以降は無効化

Progressive Disclosure（段階的開示）パターン

@import を使った設計で現場で最も推奨されているのが Progressive Disclosure パターンです。

1. CLAUDE.md（最小） — 普遍的なコンテキストだけ
2. docs/ または agent_docs/ — 状況別の詳細知識。CLAUDE.md からは「必要時にこのファイルを読め」とポインタだけ書く
3. .claude/skills/ または .claude/agents/ — ドメイン専門ワークフローを on-demand で読み込み

実装例：

# 詳細ドキュメント（必要時のみ参照）
- データベーススキーマ変更時: @docs/db-migration.md を読むこと
- 新 API エンドポイント追加時: @docs/api-conventions.md を読むこと
- 決済モジュール修正時: @docs/billing-rules.md を読むこと

CLAUDE.md 本体には「ポインタだけ」残し、詳細は必要なときだけ取り込む。これが肥大化を防ぐ最も効果的な設計です。

ルールが守られないときの根本原因と対策

「ちゃんと CLAUDE.md に書いたのに Claude が従わない」という悩みはよく聞きます。これには構造的な理由があります。

原因 1：ユーザーメッセージとして注入される

CLAUDE.md はシステムプロンプトではなく、システムプロンプト直後の「ユーザーメッセージ」として注入されます。つまり Claude にとっては「あなたが会話冒頭で伝えたお願い」と同じ扱いで、強制力はありません。後続のメッセージでユーザーが違うことを言えば、簡単に上書きされます。

対策: 本当に例外なく守らせたい処理は、CLAUDE.md ではなく Claude Code の Hook 機能で強制する。

原因 2：Lost in the Middle 問題

LLM は長文コンテキストの先頭と末尾を、中央より高精度で参照する傾向があります（Lost in the Middle 問題）。CLAUDE.md が長いと、中盤に書いたルールほど無視されやすくなります。

対策:

• 最重要ルールは冒頭に配置
• IMPORTANT: YOU MUST: NEVER: のような強調記法を使う（公式も推奨）
• 見出し・箇条書き・表で視認性を上げる

原因 3：ファイルが長すぎる

指示数が増えると、特定の指示が無視されるのではなく 全ての指示の遵守率が一様に下がることが HumanLayer の検証で報告されています。

対策: 200 行を超えたら剪定。「この行がなくなったら Claude は間違うか？」と各行に問い、No なら削除。

原因 4：表現が曖昧

「綺麗に書く」「適切に処理する」のような曖昧な指示は、Claude にとって守る基準が決まらず無視されます。

対策: 必ず検証可能な形に言い換える。「すべての関数に JSDoc を付ける」「エラーは型付きのカスタムエラークラスで投げる」など、成否が判断できる書き方にする。

CLAUDE.md テンプレート集

すぐに使える 3 パターンのテンプレートを紹介します。

ミニマル版（個人開発・小規模向け・30 行）

# MyApp

## 概要
TypeScript + Bun で書かれた API サーバー。

## 必須コマンド
- 開発サーバー: `bun run dev`
- 型チェック: `bun run typecheck`
- テスト: `bun run test`
- リント: `bun run lint`

## コーディング規約
- TypeScript strict モード必須
- 関数型スタイルを優先（for ループより map / filter / reduce）
- エラーは `AppError` 派生クラスで投げる

## テスト方針
- 新機能は必ずテストを追加
- `describe` + `it` 形式、日本語 OK

## 注意点
- DB マイグレーションは `bun run db:migrate`。手動で `ALTER TABLE` しない
- `.env.local` は git 管理外。`.env.example` を参考に作成

標準版（チーム開発向け・150 行程度・抜粋）

# ECサイト基盤

## プロジェクト概要（WHAT）
Next.js 16 App Router + TypeScript + Prisma + PostgreSQL のECサイト。
月間1,000万PV想定。

## 設計判断（WHY）
- TypeScript strict: 過去の implicit any 起因の本番バグ再発防止
- Server Actions 優先: API Route は外部連携時のみ
- 決済は Stripe 固定。他社比較は完了済みで再検討不要

## 必須コマンド（HOW）
- 開発: `pnpm dev`
- 型チェック: `pnpm typecheck`
- テスト: `pnpm test` (変更後は必ず実行)
- E2E: `pnpm e2e` (本番リリース前のみ)
- DB マイグレーション: `pnpm db:migrate`

## コーディング規約
- Server Components 優先。`use client` は必要最小限
- Prisma Client は `@/lib/prisma` から import（直接インスタンス化禁止）
- エラーハンドリングは `@/lib/errors` のカスタムエラーを使用

## IMPORTANT: 絶対守ること
- 決済処理の金額計算は必ず Decimal 型で行う（number 禁止）
- 個人情報を含むログを出力しない
- マイグレーション無しで DB スキーマを変えない

## 詳細ドキュメント（必要時に参照）
- API 設計: @docs/api-conventions.md
- 決済モジュール: @docs/billing-rules.md
- セキュリティ要件: @docs/security.md

大規模・モノレポ版（rules 活用）

monorepo-root/
├── CLAUDE.md                     # 共通ルール（80 行）
├── .claude/
│   └── rules/
│       ├── typescript.md         # TS 全般規約（paths なし＝常時）
│       ├── api.md                # paths: src/api/**
│       ├── frontend.md           # paths: apps/web/**
│       └── infra.md              # paths: infrastructure/**
├── apps/
│   ├── web/CLAUDE.md             # フロント固有
│   └── admin/CLAUDE.md           # 管理画面固有
└── packages/
    └── core/CLAUDE.md             # コアライブラリ固有

親 CLAUDE.md にはチーム共通の WHAT / WHY / HOW だけ置き、各ドメイン固有の規約は .claude/rules/*.md に paths: フロントマター付きで配置します。

AGENTS.md や他 AI ツールとの関係

近年は Cursor・Codex・Aider など複数のコーディングエージェントを併用するチームも増えました。ここで課題になるのが 「指示ファイルの二重管理」 です。

Claude Code は CLAUDE.md しか読まない

公式仕様上、Claude Code は AGENTS.md を自動では読み込みません。一方、Cursor や Codex は AGENTS.md を標準にしています。

1 ソース化の戦略

既に AGENTS.md を使っているリポジトリでは、CLAUDE.md 側で @AGENTS.md として取り込めば二重管理を避けられます。

@AGENTS.md

## Claude Code 固有の指示
- `src/billing/` 以下を変更するときは plan mode を使うこと
- マイグレーションは必ず `/compact` 前に実行すること

共通ルールは AGENTS.md に、Claude 固有の細かい指示だけ CLAUDE.md 本体に書く形です。この方式なら、どちらのツールでも最新の規約が反映されます。

関連コマンド（公式）

CLAUDE.md を運用するうえで押さえておくべき公式コマンドです。

/init は雛形作成には便利ですが、そのまま使わず必ず手動で剪定するのが鉄則です。/init はしばしば冗長な内容を生成するため、自動生成版を土台に「これは Claude が推測できるか？」と問いながら削っていきます。

HTML コメントでメンテナーメモを残せる

意外と知られていない仕様ですが、<!-- --> 形式の HTML コメントは context 注入前にストリップされます（コードブロック内は保持）。

<!-- このルールは2026-03-10のインシデント対策で追加。2026-09に見直し -->
## 決済処理の金額計算は必ず Decimal 型

メンテナーへの注意書きを CLAUDE.md に残しつつ、Claude のコンテキストは圧迫しない運用が可能です。

CLAUDE.md の「育て方」フレームワーク

CLAUDE.md は一度書いて終わりではありません。公式も「コードのように扱え」と言っています。

書き加えるシグナル

• 同じ訂正を 2 回した — 3 回目を防ぐために書く
• チームメンバーが詰まった場所 — 暗黙知を形式知化
• コードレビューで頻出する指摘 — Claude に事前に伝えておけば PR が綺麗に
• インシデントの再発防止策 — 「なぜダメか」を WHY として残す

削るシグナル

• Claude が指示なしでも正しく動くようになった
• リンター・型チェッカーで強制可能になった
• 自明すぎる内容（「綺麗なコードを書く」など）
• プロジェクトから外れた技術の名残

スキル／Hook に移すシグナル

• 手順が長く、CLAUDE.md で書くと肥大する
• 特定タスク専用（DB マイグレーション等）で常時ロード不要
• 例外なく毎回実行されなければ困る（この場合は Hook でプログラム的に強制）

「CLAUDE.md は指示、Hook は強制、Skill は専門ワークフロー」と機能を分けて考えると、各ファイルがスリムに保てます。

よくある失敗パターン

実運用でよくある失敗を整理します。

1. /init の生成結果をそのまま放置 — 冗長かつ自明な内容が混ざっているのでレビュー必須
2. リンターで強制できるルールを書いている — Claude のトークンと遵守率を浪費
3. 曖昧表現（「適切に」「きれいに」） — 守る基準がなく無視される
4. 200 行を超えても放置 — ルールが全体的に守られなくなる
5. WHY を書かない — Claude が派生ケースで誤判断
6. シークレットや接続文字列を書く — セキュリティ事故。.env 参照を指示するに留める
7. CLAUDE.local.md を .gitignore に入れ忘れる — 個人情報・社内パスが漏洩
8. サブディレクトリで親と矛盾するルール — 親子で整合性を取らないと挙動が不安定

こんな方に向いています

• Claude Code を本格的にチームで運用したい: CLAUDE.md が指示の統一と PR レビュー対象になる
• プロジェクト規約が複雑で毎回説明が必要: 永続化して運用コストを下げたい
• モノレポや大規模コードベースを運用: 階層的スコープと paths: で効率化
• 他ツール（Cursor / Codex）と併用: @AGENTS.md で 1 ソース管理したい

こんな方にはおすすめしません

• Claude Code を使わない（他ツール専用）: そもそも読み込まれない
• ルール自体がまだ固まっていない: まず運用で試して、必要なものだけ書く方が効率的
• 「書けば Claude が完璧に守る」と期待している: ユーザーメッセージ注入なので強制力は限定的。例外なく守らせたい処理は Hook で

よくある質問（FAQ）

Q1. CLAUDE.md は何行までが現実的な上限ですか？

Anthropic 公式は 200 行以内を明示推奨しています。HumanLayer の経験則では 60 行前後が最適、300 行を超えると遵守率が確実に下がるとされています。まず 200 行を守り、可能なら 100 行未満を目指すのが現実的です。

Q2. プロジェクトと個人のルールはどう分けるべきですか？

チーム共有すべき規約は ./CLAUDE.md（git 管理）、個人固有のメモは ./CLAUDE.local.md（.gitignore）、全プロジェクト共通の個人設定は ~/.claude/CLAUDE.md に分離します。CLAUDE.local.md を git 管理外にしないと、個人情報や社内パスが漏洩するので注意してください。

Q3. .claude/rules/ と @import はどう使い分けますか？

• .claude/rules/: ドメイン別ルールを「自動で」発見・連結したいとき。paths: で条件付きロードもできる
• @import: 既存のドキュメント（README、docs/ 以下のファイル）を 1 ソースとして参照したいとき

両方を組み合わせて、「共通ルールは rules、既存ドキュメントへの参照は @import」という使い分けが一般的です。

Q4. AGENTS.md と併用するときのベストな設計は？

AGENTS.md をメインソースにし、CLAUDE.md の先頭で @AGENTS.md を読み込ませる形が推奨されます。Claude 固有の指示（plan mode の使用、/compact 前の必須処理など）だけを CLAUDE.md 本体に書けば、二重管理を避けられます。

Q5. /init で自動生成されたファイルはそのまま使えますか？

使えません。/init は雛形として便利ですが、冗長な内容（自明な技術説明、リンターで強制できるルールなど）が混ざります。必ず手動で剪定し、「この行を削除したら Claude が間違うか？」と各行に問いながら絞り込んでください。

Q6. ルールを書いても Claude が従いません。どうすればいい？

主な原因は次の 4 つです。

1. ファイルが長すぎる: 200 行を超えていないか確認
2. 重要ルールが中盤に埋もれている: 冒頭に移動し IMPORTANT: で強調
3. 表現が曖昧: 「きれいに」ではなく検証可能な条件に書き直す
4. CLAUDE.md で強制しようとしている: 例外なく守らせたい処理は Hook を使う

Q7. サブディレクトリの CLAUDE.md はいつ読み込まれますか？

Claude がそのディレクトリのファイルを読んだタイミングで初めて注入されます。親ディレクトリの CLAUDE.md は launch 時に常に読み込まれますが、子は on-demand です。したがって、細かいドメインルールはサブディレクトリに置くと全体のトークンを節約できます。

Q8. /compact 後も CLAUDE.md は効いていますか？

プロジェクトルートの CLAUDE.md は /compact 後に再注入されます。ただしサブディレクトリの CLAUDE.md は、次にそのフォルダのファイルを読むまで再ロードされません。長いセッションで頻繁に compact する場合は、重要ルールはルート CLAUDE.md に集約しておくのが安全です。

まとめ

CLAUDE.md 書き方のベストプラクティスを整理します。

• 書く対象: Claude がコードを読んで推測できないことだけ
• 文量: 公式 200 行以内、最適 60 行前後、緊急上限 300 行
• 構造: WHAT / WHY / HOW の 3 層で設計
• 配置: プロジェクト共通は ./CLAUDE.md、個人は ./CLAUDE.local.md（gitignore 必須）
• 分割: 規模が増えたら .claude/rules/ と @import でドメイン別に
• 運用: コードのように PR レビュー、同じ訂正 2 回で追加、自明化したら削除
• 強制力: CLAUDE.md はガイダンス。例外なく守らせたいなら Hook へ

もっとも大切なのは、「書けば効く」ではなく「絞るほど効く」という事実です。200 行を守り、曖昧表現を排し、WHY を添え、使いながら育てる。この 4 原則を守るだけで、Claude Code の振る舞いは劇的に安定します。

関連する内容は以下の記事もあわせてご覧ください。

• Claude Code とは｜使い方・料金・できること完全ガイド
• Claude Code 使い方ガイド｜導入からベストプラクティスまで
• Claude Code Hooks 使い方｜ガードレールを自動強制する方法
• Claude Code Skills 活用ガイド｜ドメイン専門ワークフローの作り方
• Claude Code サブエージェント 使い方
• Claude Code MCP 連携ガイド