最強の CLAUDE.md 設計｜AI に効く7つの原則と肥大化の罠
「CLAUDE.md を書いたのに AI が言うことを聞かない」——その原因の多くは、ファイルが弱いからではなく長すぎるからです。最強の CLAUDE.md は情報量では決まりません。本当に効くのは、毎セッション読み込まれても破綻しない「信号密度」の高いファイルです。本記事では、Claude Code 公式ドキュメントと現場の知見をもとに、効く CLAUDE.md にするための7つの原則と、強さを殺す肥大化の罠を整理します。
CLAUDE.md は Claude Code が 毎セッションの冒頭で自動的に読み込む 指示書です。だからこそ強さは行数ではなく 信号密度 で決まります。公式ドキュメントは「肥大化した CLAUDE.md は Claude が本来の指示を無視する原因になる」と明言しており、各行に「これを消したら AI がミスするか?」と問うて削るのが出発点です。
効くファイルにする原則は7つです。小さく保つ・スタイルは Linter に逃がす・例外なき制約は強調語で書く・落とし穴(Gotchas)を最優先で書く・@import と配置で分割する・規模別に設計する・定期的に棚卸しする。中でも ROI が最も高いのは、コードを読んでも分からない 固有の罠を書いた落とし穴セクション です。
逆に強さを殺すのが 肥大化の罠 です。/init の自動生成を丸投げし、自明な常識やスタイル規約まで詰め込むと、重要なルールがノイズに埋もれて効かなくなります。CLAUDE.md は コードと同じく定期的に剪定 し、Claude の挙動が実際に変わったかで効果を検証する「育てるファイル」として扱うのが最短ルートです。
目次 (10)
- 1. 「最強の CLAUDE.md」は量ではなく信号密度で決まる
- 2. 原則1：200〜300 行以内に保ち、毎行を「削れないか」で点検する
- 3. 原則2：コードスタイルは Linter に任せ、固有知識だけを書く
- 4. 原則3：例外を許さない制約は IMPORTANT / YOU MUST で強調する
- 5. 原則4：最強の ROI は「落とし穴(Gotchas)」セクション
- 6. 原則5：@import と配置スコープで肥大化を防ぐ
- 7. 原則6：個人・チーム・モノレポで設計を変える
- 8. 原則7：月次で棚卸しし、挙動が変わったかで検証する
- 9. 肥大化の罠：最強を殺す5つのアンチパターン
- 出典
1. 「最強の CLAUDE.md」は量ではなく信号密度で決まる
CLAUDE.md は、Claude Code が会話を開始するたびに自動で読み込む特別なファイルだ。プロジェクト固有のルールをコードからは推測できない形で持たせる、いわば常設の前提知識になる。
ここで多くの人が誤解する。「たくさん書けば書くほど賢く振る舞う」と考えてしまうのだ。実際は逆だ。Claude Code 公式のベストプラクティスは、「肥大化した CLAUDE.md は Claude が本来の指示を無視する原因になる(Bloated CLAUDE.md files cause Claude to ignore your actual instructions)」と明確に警告している。
つまり最強の CLAUDE.md とは、長いファイルではなく 信号密度の高いファイル だ。ノイズになる一行を削り、効く一行だけを残す。公式が勧める判定基準はシンプルで、各行について「これを消したら Claude がミスをするか?」と自問し、しないなら削る。この一点を軸に、以下の7つの原則を積み上げていく。
2. 原則1：200〜300 行以内に保ち、毎行を「削れないか」で点検する
CLAUDE.md は全セッションで読み込まれる。これはトークンを毎回消費するということであり、Claude の文脈枠(コンテキストウィンドウ)を着実に圧迫する。公式が強調するとおり、コンテキストが埋まるほど Claude の性能は劣化し、前半の指示を「忘れ」始める。長い CLAUDE.md は、それ自体が性能低下の原因になりうる。
Zenn の運用ベストプラクティス記事は、目安として「300 行以下」「150〜200 個程度の指示」に収めることを推奨している。この上限は、LLM が一度に安定して扱えるルール数の現実的な天井だ。
行数を抑えるコツは、追加するときの慎重さよりも 削るときの大胆さ にある。新しい罠に気づくたび追記していくと、ファイルは必ず膨らむ。月に一度は全行を見直し、「消したら Claude がミスするか?」を満たさない行を機械的に剪定する。これを習慣にするだけで、密度は保たれる。
3. 原則2：コードスタイルは Linter に任せ、固有知識だけを書く
CLAUDE.md に書いて最も無駄になりがちなのが、インデント幅・クォートの種類・import の並び順といったスタイル規約だ。これらは CLAUDE.md に書くより、Linter や Formatter で機械的に強制したほうが遥かに確実に守られる。AI への「お願い」は確率的だが、Formatter は決定的だからだ。
では CLAUDE.md には何を書くべきか。公式は「含めるべきもの」と「除外すべきもの」を明確に対比している。
| ✅ 含める | ❌ 除外する |
|---|---|
| Claude が推測できない固有コマンド | コードを読めば分かること |
| デフォルトと異なるコード規約 | 言語標準の一般的な慣習 |
| テスト方針・使うテストランナー | 詳細な API ドキュメント(リンクで十分) |
| 分岐命名・PR 規約などの作法 | 頻繁に変わる情報 |
| プロジェクト固有のアーキ判断 | ファイル単位の構造説明 |
| 必須 env など環境のクセ | 「きれいに書け」等の自明な助言 |
判断軸は「Claude がコードを読んでも推測できないか」の一点だ。推測できることはすべて Linter とコードに任せ、CLAUDE.md には固有知識だけを残す。
4. 原則3：例外を許さない制約は IMPORTANT / YOU MUST で強調する
CLAUDE.md のルールは、すべてが同じ重みで読まれるわけではない。どうしても守らせたい制約には、強調を付けて従順性を上げる手がある。公式も「IMPORTANT や YOU MUST のような強調語を加えることで遵守率を改善できる」と明記している。
たとえば「本番環境の .env は絶対に読み込まない」「legacy/ 以下は変更しない」といった、踏むと事故になる制約は、ただ書くだけでなく強調語付きで書く。
ただし注意点がある。CLAUDE.md はあくまで助言(advisory)であり、100% の保証はない。「例外なく毎回必ず実行されてほしい」処理は、CLAUDE.md ではなく Hook に逃がすのが正解だ。公式が指摘するとおり、Hook は決定的(deterministic)に動作し、そのアクションが起きることを保証する。強調語は遵守率を上げる手段であって、絶対の保証ではないと割り切る。
5. 原則4：最強の ROI は「落とし穴(Gotchas)」セクション
CLAUDE.md の中で最も投資対効果が高い一行は、コードを読んでも絶対に分からない 固有の罠 だ。公式の「含めるべきもの」にも「よくある落とし穴・非自明な挙動(Common gotchas or non-obvious behaviors)」が挙がっている。
たとえば次のような情報は、リポジトリのどこにも書かれておらず、AI が踏むと確実に事故になる。
- このサービスはローカルでは動くが、特定の env が無いと CI で必ず落ちる
- このモジュールは見た目は使えそうだが、別チーム管轄で触ると壊れる
- この関数は歴史的経緯で
foo()を呼んでおり、bar()に変えてはいけない
こうした「最も信号密度の高い情報」を集めた落とし穴セクションは、たった数行で AI の地雷踏みを劇的に減らす。CLAUDE.md を強くしたいなら、まずここから書くのが近道だ。
6. 原則5：@import と配置スコープで肥大化を防ぐ
密度を保ちながら情報量を確保するには、CLAUDE.md 本体を薄く保ったまま、詳細を外部に切り出す。Claude Code は @path/to/import 構文での読み込みに対応しており、スキーマ・API 仕様・ドメインルールといった重い情報は別ファイルにして、本体からは場所と概要だけを指す形にできる。
さらに、たまにしか使わない手順や専門知識は、CLAUDE.md に常駐させず Skill 化するのが公式推奨だ。Skill は必要なときだけ読み込まれるため、毎回の会話を膨らませない。
配置場所もスコープ管理の武器になる。代表的な置き場所は次のとおりだ。
~/.claude/CLAUDE.md：全プロジェクト共通の個人設定に使う./CLAUDE.md：git にコミットしてチームで共有する./CLAUDE.local.md：.gitignoreに入れる個人専用メモ- 親・子ディレクトリ：モノレポで階層ごとにルールを分ける
役割ごとにファイルを分けることで、一つひとつを短く、効く状態に保てる。
7. 原則6：個人・チーム・モノレポで設計を変える
最強の形はプロジェクト規模で変わる。同じテンプレを貼り回すのではなく、構成に合わせて設計を切り替える。
個人開発なら、よく使う言語の好みやコマンドは ~/.claude/CLAUDE.md のグローバル設定に寄せ、各リポジトリの CLAUDE.md は固有事項だけに絞る。これで重複が消える。
チーム開発では、CLAUDE.md を必ず git にコミットして共有する。公式が言うとおり、チーム全員が同じファイルに貢献し続けることで、その価値は時間とともに複利的に増していく(The file compounds in value over time)。AI の出力品質も均質化され、誰が頼んでも同じ基準のコードが返る。
モノレポでは、ルートに全体共通ルールを、各パッケージに固有ルールを階層配置する。ルートと作業中ディレクトリの CLAUDE.md は自動で合成して読み込まれるため、巨大な一枚岩にせず、責務ごとに分割したまま運用できる。
8. 原則7：月次で棚卸しし、挙動が変わったかで検証する
CLAUDE.md は書いて終わりではない。公式は「CLAUDE.md をコードと同じように扱え——うまくいかないときに見直し、定期的に剪定し、Claude の挙動が実際に変わったかで変更をテストせよ」と述べている。生きたドキュメントとして育てる前提だ。
具体的な運用ルーティンは次の流れがよい。
/initでプロジェクト構造から叩き台を自動生成する- AI が同じミスを繰り返したら、その対策を一行追加する
- 逆に、指示を消しても正しく動く行は削除するか Hook に変換する
- 月に一度、全行を「削れないか」基準で剪定する
ポイントは検証の仕方だ。ルールを足したり消したりしたあと、Claude の振る舞いが本当に変わったかを観察する。変わらなければ、その一行は効いていない。挙動ベースで効果を測ることで、ファイルは膨らまずに強くなり続ける。
9. 肥大化の罠：最強を殺す5つのアンチパターン
最後に、せっかくの CLAUDE.md を弱くしてしまう典型的な失敗を挙げる。公式も「過剰に書き込まれた CLAUDE.md(The over-specified CLAUDE.md)」を代表的な失敗パターンとして警告している。長すぎると重要なルールがノイズに埋もれ、AI は半分を無視する。
避けるべきアンチパターンは次の5つだ。
/initの自動生成をそのまま丸投げし、見直さずに肥大化させる- 「きれいなコードを書け」のような、AI が言われなくてもやる自明な助言を書く
- インデントやクォートなど、Linter に任せるべきスタイル規約を全部詰め込む
- 頻繁に変わる情報やファイル単位の構造説明など、すぐ陳腐化する内容を書く
- 長い解説・チュートリアル、あるいは互いに矛盾するルールを混在させる
対処は一つ、容赦なく剪定することだ。Claude が指示なしでも正しく振る舞うなら、その行は削除するか Hook に変換する。最強の CLAUDE.md は「全部書いたファイル」ではなく、「効く一行だけを残したファイル」だと覚えておきたい。
Clauder Navi 編集部
