CLAUDE.md の階層構造と遅延読み込み（Lazy Loading）
プロジェクトの規模が大きくなるほど、ルートの CLAUDE.md 一つにすべての API 仕様や DB スキーマを入れると、毎セッションで数千トークンが無駄になります。
1. 読み込み方式を理解する（重要）
フォルダ別 CLAUDE.md 戦略を使う前に、読み込み方式をまず理解しましょう。
| 位置 | 読み込みタイミング |
|---|---|
| 実行位置基準の上位 CLAUDE.md | セッション開始時に即座にすべて読み込み |
| 実行位置基準の下位 CLAUDE.md | 該当フォルダのファイルを実際に作業するときのみ読み込み ✅ |
⚠️
@構文でファイルを参照すると、本当の Lazy Loading ではありません。@docs/db-schema.mdのように参照すると、セッション開始時に即座に読み込まれてトークンをすべて消費します。
本当の Lazy Loading はフォルダ内部に CLAUDE.md を置く方式でのみ動作します。
2. フォルダ別 CLAUDE.md 分離戦略（本当の Lazy Loading）
ドメインや機能別にフォルダ内部に別途 CLAUDE.md を作成してください。
📁 プロジェクトルート/
├── CLAUDE.md ← 常に読み込み（共通ルールのみ、50〜100行以下）
├── src/
│ ├── features/
│ │ └── auth/
│ │ └── CLAUDE.md ← auth フォルダ作業時のみ読み込み
├── supabase/
│ └── CLAUDE.md ← supabase フォルダ作業時のみ読み込み
└── docs/
└── CLAUDE.md ← docs フォルダ作業時のみ読み込みClaude Code はルートから実行時、下位フォルダの CLAUDE.md をすぐには読まず、該当フォルダ内のファイルを実際に編集するときのみ読み込みます。
3. Pointer（参照）方式 — いつ使うべきか
@ 参照方式はトークン節約が目的ではなく、CLAUDE.md ファイル構造を読みやすく整理するときに使います。
## References
- アーキテクチャ全体構造: @docs/architecture.md
- DB スキーマ: @docs/db-schema.md
- API コンベンション: @docs/api-patterns.mdこの方式はセッション開始時に参照されたファイルをすべて読み込むため、ファイルが大きいとむしろ逆効果です。
参照ファイルはできるだけ短く、要点のみを含めるべきです。
4. ルート CLAUDE.md — 軽く保つ方法
ルート CLAUDE.md に入れるものと除外すべきものを明確に区別してください。
入れるもの（共通ルール）
- 技術スタックの一行要約
- よく使うコマンド（
npm run dev、npm run testなど） - 言語・コーディングコンベンション（ES modules、camelCase など）
- 絶対に触れてはいけないファイル・フォルダ
除外すべきもの（下位 CLAUDE.md に移動）
- 特定ドメインの API 仕様
- DB スキーマの詳細
- 特定機能のビジネスロジックルール
💡 実務の教訓: 1,500行の CLAUDE.md は、むしろ Claude がルールを無視するようになります。
CLAUDE.md は時間が経つほど短くなる方向が正しいです。
5. 重要なルールは強調表示する
CLAUDE.md が長くなるほど、Claude がルールを読み飛ばす可能性があります。絶対に破ってはいけないルールには強調キーワードを付けておきましょう。
IMPORTANT: 絶対に .env ファイルを編集しないでください。
YOU MUST: すべての DB クエリは RLS ポリシーを通過する必要があります。6. CLAUDE.local.md（個人設定）
チームと共有しない個人設定は CLAUDE.local.md に別途記述し、.gitignore に追加してください。
⚠️ 公式ドキュメントでは
CLAUDE.local.mdを deprecated として分類し、@import 方式を推奨しています。ただし現在も動作しており、チーム環境での個人設定分離用途としては依然として有用です。
💡 一言まとめ: 本当の Lazy Loading ＝ フォルダ別 CLAUDE.md 分離。
@参照は即座に読み込まれます。