この記事で紹介する Claude Code × MCP 連携をさらに活用するなら pay-per-call-mcp もチェックしてください。Claude から外部 API を USDC 課金付きで呼び出せます。
この記事でわかること
- CLAUDE.md が肥大化すると Claude Code の精度が落ちる理由
- グローバル・プロジェクト・ディレクトリの 3 層設計でコンテキストを最小化する方法
- 「コーディングルール」「プロジェクト情報」「禁止事項」を分割する実践テンプレート
-
@includeでファイルを分割して管理コストを下げるテクニック - 300 行 CLAUDE.md を 60 行に圧縮した実際の Before / After
はじめに
Claude Code を使い始めて 1〜2 ヶ月経つと、多くの人が「なんか最近 Claude の精度落ちてきた気がする…」という壁に当たります。
原因のほとんどは CLAUDE.md の肥大化です。「やってほしいこと」を書き足し続けた結果、重要なルールが埋もれ、矛盾するルールが共存し、Claude が混乱します。
この記事では、実際に 300 行超の CLAUDE.md を 60 行に圧縮して精度が劇的に改善した話を共有します。
CLAUDE.md の読み込み階層を理解する
Claude Code は複数の CLAUDE.md を階層的に読み込みます：
~/.claude/CLAUDE.md ← グローバル（全プロジェクト共通）
<project>/.claude/CLAUDE.md ← プロジェクトルール（チーム共有）
<project>/<subdir>/CLAUDE.md ← ディレクトリ固有ルール
重要: 全ての CLAUDE.md が毎回コンテキストに入ります。つまり 300 行のファイルがあると、毎ターン 300 行分のトークンを消費しながらスタートします。
Before: よくある肥大化 CLAUDE.md（300 行の例）
# プロジェクトルール
## コーディングスタイル
- TypeScript を使う
- ESLint を通す
- Prettier でフォーマット
- import は絶対パス
- 型は any を使わない
- null より undefined を使う
- ...（100 行続く）
## コミットルール
- feat: で始める
- fix: バグ修正
- docs: ドキュメント
- ...（50 行続く）
## アーキテクチャ
- Clean Architecture を採用
- レイヤー構成: presentation / application / domain / infrastructure
- ...（80 行続く）
## 禁止事項
- console.log を本番コードに残さない
- magic number を使わない
- ...（70 行続く）
問題点
- 重要度が均一化: 全ルールが同じ重みで読まれる
- 矛盾が発生しやすい: 「null を使わない」「null チェックを必ずする」が混在
- コンテキスト汚染: 関係ないルールが毎回ロードされる
- メンテ不能: 誰も全部読まないので陳腐化する
After: 60 行の最小 CLAUDE.md + @include 分割
# CLAUDE.md — <プロジェクト名>
## 必読: このプロジェクトについて
Node.js 22 + TypeScript 5.4 の REST API サーバー。
DB は PostgreSQL（Prisma ORM）。
テストは Vitest。
## 最重要ルール（必ず守る）
1. `any` 型禁止。`unknown` + type guard を使う
2. DB 直アクセスは `src/infra/` 以外から禁止
3. PR 前に `npm test` が通ること
## コーディングスタイル
@include .claude/rules/coding-style.md
## コミット規約
@include .claude/rules/commit-convention.md
## よく使うコマンド
- `npm run dev` — 開発サーバー起動
- `npm test` — テスト実行
- `npx prisma studio` — DB GUI
分割ファイルの例
<!-- .claude/rules/coding-style.md -->
- import: tsconfig の paths alias を使う（例: @/services/...）
- 非同期: async/await（Promise.then は禁止）
- エラー: Result 型（neverthrow）を使う
- ログ: console.* 禁止、logger.ts を使う
<!-- .claude/rules/commit-convention.md -->
形式: `type(scope): subject`
type: feat / fix / refactor / test / docs / chore
subject: 英語、現在形、50文字以内
圧縮の 5 原則
1. 最重要ルールは 3 つまで
人間も AI も、一度に覚えられるルールは 3〜5 個が限界です。本当に重要なものだけを 番号付きリストで書く。
## 最重要ルール
1. src/domain/ はフレームワーク非依存を維持する
2. 外部 API 呼び出しは必ずリトライ処理を入れる
3. テスト書かずにマージしない
2. 「何をするか」より「何をしないか」を書く
Claude はデフォルトで良いコードを書こうとします。「する」ルールを大量に書くより「しない」禁止事項を 5 個書く方が効果的。
3. プロジェクト固有情報だけを書く
TypeScript のベストプラクティスは Claude がすでに知っています。「TypeScript を使う」「型安全にする」といった一般論は削除。
4. @include で認知負荷を下げる
メインの CLAUDE.md は「目次」として機能させ、詳細は @include でリンク。Claude は必要に応じてロードします。
5. 定期的に「なぜ書いたか」を見直す
月 1 回 CLAUDE.md を全文レビュー。「これ、もうやらかしてないから不要では？」というルールは削除。
グローバル CLAUDE.md の設計
~/.claude/CLAUDE.md は全プロジェクトで有効なので最小限に：
# Global Claude Config
## 絶対禁止
- `rm -rf` は絶対に実行しない
- 秘密鍵・APIキーをコードにハードコードしない
- 本番 DB に直接 write しない（必ず確認を求める）
## 好みのスタイル
- 日本語で回答する
- コードブロックには言語を明記する
- 長い説明より動くコードを優先する
よくある失敗パターンと対策
| 失敗パターン | 対策 |
|---|---|
| 「〜してください」を大量に書く | 「〜禁止」に書き換える |
| 全ブランチ・全環境のルールを 1 ファイルに | ディレクトリ別 CLAUDE.md に分割 |
| 過去のバグ対応ルールを蓄積し続ける | 月次レビューで削除 |
| 矛盾するルールが共存 | 「最重要ルール」セクションで上書き宣言 |
| チームメンバー全員がルールを追記 |
.claude/rules/ に分割し PR レビュー必須に |
Before / After の比較
| 指標 | Before（300行） | After（60行+@include） |
|---|---|---|
| 1ターンのコンテキスト消費 | 約4,000トークン | 約800トークン |
| ルールの遵守率（主観） | 60〜70% | 90%以上 |
| CLAUDE.md のメンテ時間 | 月2時間 | 月15分 |
| 新メンバーのオンボード時間 | 1時間 | 10分 |
まとめ
CLAUDE.md 設計の要点：
- 最重要ルールは 3 つに絞る（番号付きリスト）
- 「しないこと」を書く（禁止リスト）
- プロジェクト固有情報のみ（一般論は削除）
-
@includeで詳細を分割（メインは目次として機能） - 月次レビューで削除する（追加より削除を優先）
「Claude Code の精度が落ちてきた」と感じたら、CLAUDE.md のダイエットを試してみてください。
よくある質問（FAQ）
Q. @include はどのパスから書きますか？
A. プロジェクトルートからの相対パスです。.claude/rules/coding-style.md のように書きます。~/ からの絶対パスも使えます。
Q. CLAUDE.md は .gitignore に入れるべきですか？
A. プロジェクト CLAUDE.md はチームで共有するためコミット推奨です。グローバル（~/.claude/CLAUDE.md）は個人設定なので git 管理不要。秘密情報（APIキーのパスなど）は書かないこと。
Q. Skills（.claude/skills/）と CLAUDE.md の違いは？
A. CLAUDE.md は「常に有効なルール」で、Skills は「必要なときだけ呼び出す手順書」です。繰り返す作業（デプロイ手順、PR の作り方など）は Skills に切り出すと CLAUDE.md がすっきりします。
Q. チームで CLAUDE.md を共有する際の注意点は？
A. .claude/rules/ 以下のファイルも含めてコミットし、追加時は必ず PR レビューを通すルールを設けましょう。ルールの「理由」をコメントで残すと後から削除しやすくなります。