この記事で紹介する Claude Code × MCP 連携をさらに活用するなら pay-per-call-mcp もチェックしてください。Claude から外部 API を USDC 課金付きで呼び出せます。

npm: https://www.npmjs.com/package/pay-per-call-mcp
Glama: https://glama.ai/mcp/servers/@evid-ai/pay-per-call-mcp

この記事でわかること

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 レビューを通すルールを設けましょう。ルールの「理由」をコメントで残すと後から削除しやすくなります。