CLAUDE.mdは「4層」に分けると安定する — 1ファイル運用をやめる日
肥大化したCLAUDE.mdのルールが後半から無視される理由と、Claude Codeが標準サポートする4層構造（グローバル/プロジェクト/ローカル/ディレクトリ）への分割方法を解説します。常駐3層を約300行に抑え、ルール遵守を安定させる実践ガイドです。
この記事で学べること
- なぜ肥大化した CLAUDE.md のルールは「後半から」無視されるのか
- Claude Code が標準サポートする CLAUDE.md の4層構造 と各層の使い分け
- 4層に増やしてもコンテキストが溢れない理由（常駐3層 + オンデマンド1層）
- 既存の CLAUDE.md を今日から分割する3ステップ
1. 「書いたのに無視される」の正体
Claude Code を使い込むほど、CLAUDE.md は太っていきます。ビルドコマンド、コード規約、API の約束事、チームの禁止事項、個人の好み、3ヶ月前の設計判断、先週足した一時ルール……。
気づけば 800 行。そしてある日、こんな症状に出会います。
- ファイル末尾に書いたルールがよく無視される
- 「Lombok は使うな」と書いたのに使ってくる
- セッションが長くなると、定義したはずの好みを忘れる
- 新しいルールを足すたびに、古いルールの効きが悪くなる
「Claude が賢くないのでは」と思いがちですが、原因は逆です。あなたの CLAUDE.md が、Claude に消化できる量を超えているのです。
メカニズム: すべての行が「注意力」を奪い合う
CLAUDE.md はセッション開始時に全文がそのままコンテキストに注入されます。つまり CLAUDE.md の1行1行が、他のすべての行と Claude の注意力を奪い合っている状態です。
元記事は、最先端モデルが確実に従える指示数を約 150〜200 条と見積もっています（公式仕様ではなく経験則ですが、体感とよく一致します）。この範囲を超えると、遵守度は一気にゼロになるのではなく、ファイルの後半から1条ずつ、静かに崩れていきます。だから気づきにくい。800 行の CLAUDE.md の後半は、実質「書いていないのと同じ」になっているわけです。
2. 解決策: Claude Code 標準の「4層構造」
実は Claude Code は、CLAUDE.md を 4つの層から読み込み、起動時に自動で統合する仕組みを最初から持っています。多くの人はこのうち「プロジェクト層」しか使っていません。だからその1ファイルだけが太り続けるのです。
| 層 | パス | スコープ | 置くもの | git |
|---|---|---|---|---|
| グローバル層 | ~/.claude/CLAUDE.md | 全プロジェクト | 個人の好み・ツール習慣 | 対象外 |
| プロジェクト層 | <repo>/CLAUDE.md | 当該プロジェクト | 構成・コマンド・チーム規約 | コミットする |
| ローカル層 | <repo>/CLAUDE.local.md | 当該プロジェクト（自分だけ） | 自分の環境・一時ルール | .gitignore へ |
| ディレクトリ層 | <subdir>/CLAUDE.md | そのサブディレクトリ | モジュール固有の約束・罠 | コミットする |
層が競合したときは、より具体的な層が優先されます。
グローバル層: 「どのプロジェクトでも、私はこうする」
開発者としてのあなたの「デフォルト設定」です。プロジェクトを移っても効きます。
# ~/.claude/CLAUDE.md
## My Defaults
- 回答は日本語で
- コードコメントは英語で
- Maven より Gradle を優先（プロジェクトが対応していれば）
- Spring Boot の組み込み機能を優先し、余計な依存を増やさない
## Tool Preferences
- IDE: VS Code
- Git: GUI ではなくコマンドライン
置くのは「あなたという人に付く情報」だけ。プロジェクト固有の設定を書いてはいけません。
プロジェクト層: 「チームの憲法」
git にコミットしてチームで共有する1枚です。原則はただ1つ——Claude が自力で推測できないことだけを書く。
# <repo>/CLAUDE.md ← git にコミット
## Commands
- Build: `./gradlew build`
- Test all: `./gradlew test`
- Test single: `./gradlew test --tests "com.example.XxxTest"`
## Architecture
Spring Boot 3.2 + Spring Cloud の標準3層。
Controller → Service → Repository → MySQL。
外部 API 呼び出しは必ず Gateway インターフェース経由。
## Code Style
- Lombok は使わない。コンストラクタインジェクション
- 例外メッセージには userId + requestId を必ず含める
- DB 操作には @Transactional(readOnly=true) か書き込みモードを明示
## Do Not
- Controller に業務ロジックを書かない
- Entity をそのままフロントに返さない
- Gateway を迂回して外部 API を直接呼ばない
目安は 200 行以内。超えた分はサブディレクトリの CLAUDE.md や Skills に切り出します。
ローカル層: 「自分のマシンだけの補足」
チーム共有ファイルに書くべきでない、自分の環境だけの情報の置き場です。
# CLAUDE.local.md ← .gitignore に追加
## My Dev Environment
- DB 接続: localhost:3306、アカウント root/root
- Redis: localhost:6379、パスワードなし
- デバッグポート: 5005
## Temp Constraints
- token-service は自分がリファクタリング中。当面変更しないこと
- 今スプリントはバグ修正優先。新機能は作らない
判定基準はシンプルです: 「自分にはあるが、他人にはない」情報かどうか。DB のポートも、進行中の個人作業も、他人には当てはまりません。
ディレクトリ層: 「モジュール専用の細則」
大きなプロジェクトでは、モジュールごとに約束事が違います。ルートの CLAUDE.md でそこまで面倒を見ると肥大化するだけです。
<repo>/
CLAUDE.md ← プロジェクト全体のルール
user-service/
CLAUDE.md ← ユーザーモジュールのルール
payment-service/
CLAUDE.md ← 決済モジュールのルール
# user-service/CLAUDE.md
## API の約束
- 全エンドポイントに @PreAuthorize の権限チェック必須
- パスワードは BCrypt 必須。平文保存禁止
- ユーザー ID はハイフンなし UUID
## よくある罠
- JWT の解析は自作せず SecurityUtils.getCurrentUserId() を使う
- ユーザーキャッシュのキー形式: user:{userId}:profile
- UserRepository を直接呼ばず UserService 経由（キャッシュ層がある）
こうした細則をルートに書くと全モジュール作業時に読み込まれて無駄ですが、ディレクトリ層に置けば Claude がそのディレクトリのファイルを操作するときだけ読み込まれます。
3. なぜ4層でも「太らない」のか — 常駐3層 + オンデマンド1層
ここがこの手法の核心です。ファイルを4つに増やしても Claude が溢れないのは、ロード方式が違うからです。
| 層 | ロードタイミング | 常にコンテキストにある？ |
|---|---|---|
| グローバル層 | セッション開始時 | ✅ 常駐 |
| プロジェクト層 | セッション開始時 | ✅ 常駐 |
| ローカル層 | セッション開始時 | ✅ 常駐 |
| ディレクトリ層 | そのディレクトリのファイル操作時のみ | ❌ オンデマンド |
常駐するのは前の3層だけで、合計はおよそ 300 行以内に収まります（グローバル 50 + プロジェクト 200 + ローカル 50 が目安）。ディレクトリ層はいくら細かく書いても、無関係な作業中はコンテキストを1行も消費しません。ユーザーモジュールを触るときはユーザーの規則が載り、決済モジュールに移ればユーザーの規則は外れる——そういう動きです。
「階層が明確なほど安定する」の正体は、ファイルが増えることではなく、1ファイルあたりの負荷が減り、1ルールあたりに向けられる注意力が濃くなることです。
4. 実践: その1行、どの層に置く？
振り分けに迷ったら、次の3つの質問を順に当てるだけです。
- 個人（自分の好み）に紐づく情報？ → Yes ならグローバル層
- 自分の開発マシンだけの特殊設定？ → Yes ならローカル層
- 特定のモジュール限定の規則？ → Yes ならディレクトリ層
- すべて No → プロジェクト層（ただし「Claude が推測できないこと」だけ）
やりがちな4つのアンチパターン
- ローカル情報をプロジェクト層に書く。 「DB は localhost:3306」はチーム共有ファイルに入れない。その接続先を使うのはあなただけ。→
CLAUDE.local.mdへ。 - モジュール規則をプロジェクト層に書く。 ユーザーモジュールの「BCrypt 必須」を、決済モジュールしか触らない人にまで読ませない。→
user-service/CLAUDE.mdへ。 - 何でもプロジェクト層に詰め込む。 コマンド・個人の好み・モジュール規則・一時制約が全部ルートにある状態。→ 各層へ分割。
- 200 行を超えても放置する。 「まだ動いてるから大丈夫」が一番危険。遵守度の低下は漸進的で、長く書いてあったルールが破られたと気づいた時にはもう遅い。→ 200 行を超えたら能動的に分割。
今日やること: 3ステップの引っ越し
今の CLAUDE.md を開いて、次の行を移動させましょう。
- 個人の好み →
~/.claude/CLAUDE.md - 自分のマシン固有の設定 →
CLAUDE.local.md（.gitignoreに追加） - モジュール限定の規則 →
<サブディレクトリ>/CLAUDE.md
移動が終わったルートの CLAUDE.md は、目に見えて痩せているはずです。行数が減ることは弱くなることではありません。減ったぶん、残った1行1行の重みが増します。Claude がようやく、あなたの書いたルールを全部「見える」ようになるからです。
まとめ
| 層 | 役割 | ひとことで言うと |
|---|---|---|
| グローバル | 自分の習慣 | 「どのプロジェクトでも私はこう」 |
| プロジェクト | チームの憲法 | 「このプロジェクトで必ず守る底線」 |
| ローカル | 自分の環境 | 「私のマシンはこう設定されている」 |
| ディレクトリ | モジュール細則 | 「このモジュールだけの特別ルール」 |
CLAUDE.md は「1ファイルにたくさん書くほど良い」ものではありません。「各層が少しずつ受け持ち、合わせて全体をカバーする」——これが Claude Code を安定させる設計です。
注記: 本文中の「150〜200 条」という数値は元記事の経験則であり、公式仕様ではありません。また層の優先順は「より具体的な層が優先」という原則で理解してください。
Claude Code の導入に迷ったら
初回30分は無料。現場目線でご相談に乗ります。
関連記事
Claude Code Superpowers入門｜AIに手順を飛ばさせない14のスキル
Claude Codeが「動くけれど頼んでいないことまでやる」原因は、賢さではなく手順を飛ばすことにあります。Superpowersが14個のスキルで設計・計画・実装・デバッグをどう縛るのか、v6.3.0時点の実挙動に沿って、スキルの選び方と使い分けまで解説します。
Claude Code コマンド整理術｜「重い」の正体はコンテキスト
Claude Code の応答が重くなる原因は、モデルの性能ではなくコンテキストの使い切りにあります。有限のコンテキストウィンドウを起点に、/context・/compact・/clear など主要コマンドを「減らす・見る・戻す」の3つの役割で整理し、症状別の使い分けを解説します。
Claude Code プランモード入門｜「動くけど違う」を減らす3ステップ
Claude Code が「動くけど求めたものと違う」コードを返すのは、範囲と完了条件が渡っていないからです。プランモードで探索・計画・実装を分ける手順と、AI自身が合否を判定できる検証の書き方、テストがない場合の代替まで解説します。