CLAUDE.mdは「削る」が9割──コンテキスト汚染・矛盾ルール・重複指示の3大アンチパターンと優先度付けの技術

はじめに：あなたのCLAUDE.mdは「太りすぎ」ていないか

Claude Codeを使い始めてしばらく経つと、多くの開発者が同じ罠にはまります。「もっと精度を上げたい」「この動作をやめさせたい」と思うたびに行を追加し続けた結果、CLAUDE.mdが100行を超える巨大ファイルになっているのです。

典型的な経緯はこうです。最初は数行だった設定が、問題が起きるたびに「とりあえず追記」で膨れ上がっていきます。「コミットメッセージは日本語で」「テストを必ず書け」「説明は詳細に」「でも簡潔に」──矛盾する指示が静かに積み重なっていきます。

指示が多いほどClaudeは賢く動く、という考えは誤解です。 実際の開発現場では、CLAUDE.mdが肥大化すればするほど応答品質が下がるという逆説的な現象が確認されています。コンテキストウィンドウという有限なリソースを、不要なルールが食い潰してしまうからです。

本記事では、CLAUDE.mdを劣化させる3大アンチパターンを解剖し、「削る技術」としての優先度付けフレームワークを実践的に解説します。

第1章：CLAUDE.mdとは何か──役割と限界を正しく理解する

CLAUDE.mdの本来の目的

CLAUDE.mdは、プロジェクト固有のルールや制約をClaudeに伝えるための設定ファイルです。システムプロンプト的な役割を担い、セッション開始時に自動的に読み込まれます。

設置場所による役割の違いを理解しておくことが重要です。

ファイルパス	スコープ	用途
`~/.claude/CLAUDE.md`	グローバル	全プロジェクト共通のルール
`プロジェクトルート/CLAUDE.md`	ローカル	そのリポジトリ専用のルール
`サブディレクトリ/CLAUDE.md`	サブツリー	特定ディレクトリ専用のルール

グローバル設定には「コミットメッセージの言語」「デフォルトの応答スタイル」など普遍的なルールを置き、ローカル設定にはプロジェクト固有の技術スタックや制約を記述するのがベストプラクティスです。

コンテキストウィンドウにおける位置づけ

技術的に正確な表現をすれば、CLAUDE.mdはコンテキストウィンドウの「先頭部分」を占有します。CLAUDE.mdが1,000トークンを消費していれば、コード、会話履歴、ツール出力が使えるスペースはその分だけ削られます。

Claude 3.5 SonnetやClaude 3.7 Sonnetは大きなコンテキストウィンドウを持ちますが、それでもリソースは有限です。200,000トークンのウィンドウのうち、ルールに2,000〜3,000トークンを費やすのは、大きなコードベースを扱うときに確実に性能低下を引き起こします。

「Claudeへの記憶」という誤解

よく見られる誤解として、「CLAUDE.mdに書けばClaudeが覚えてくれる」という認識があります。しかし実際には、CLAUDE.mdはセッションをまたいだ「記憶」ではなく、毎回ゼロから読み込まれる「説明書」です。

長期的な状態管理が必要な場合は、/memoryコマンドや外部ストレージ（プロジェクトのWikiなど）との使い分けが必要です。CLAUDE.mdは「今このセッションで守ってほしいルール」を書く場所として捉えてください。

第2章：3大アンチパターン徹底解説

アンチパターン①：コンテキスト汚染（Context Pollution）

コンテキスト汚染とは何か

コンテキスト汚染とは、関係のない情報・古い情報がClaudeの判断を歪める現象です。「念のため書いておこう」という善意の追記が、時間の経過とともに負の連鎖を生みます。

具体的には次のようなケースが典型例です。

廃止ライブラリへの言及: 「Momentjsを使ってください」という指示が残り、Day.jsへ移行した後も誤った判断を誘発する
異なるプロジェクトのルール混入: グローバルCLAUDE.mdにA社専用の制約が混入し、全プロジェクトに悪影響を与える
フェーズ依存のルール: 「まだ開発中なのでエラーハンドリングは省略可」という指示が、本番移行後も生き続ける

コンテキスト汚染の検出方法

「この指示は今も有効か？」を問うセルフチェックリストを活用してください。

## コンテキスト汚染チェックリスト
- [ ] このルールは今のコードベースに適用されるか？
- [ ] 参照しているライブラリ・フレームワークは現在も使用中か？
- [ ] このルールを書いた当時のコンテキストは今も同じか？
- [ ] このルールは削除しても誰も困らないか？

運用ルールとして、各ルールに最終確認日を記録することも効果的です。

# プロジェクトルール（最終確認: 2025-07-01）

アンチパターン②：矛盾ルール（Conflicting Rules）

矛盾ルールが生まれるメカニズム

矛盾ルールは主に2つの経路で生まれます。複数人での編集による思想の衝突と、時系列での追記による相殺です。

チームAは「説明は詳細に書け」と追記し、チームBは「簡潔に答えよ」と追記します。どちらの指示が優先されるかが明示されていなければ、Claudeは都度デフォルト動作を選ぶしかありません。

よく見られる矛盾パターン

実際の開発現場でよく見られる矛盾の具体例を挙げます。

# ❌ 矛盾ルールの例

## 応答スタイル
- 回答は必ず簡潔に3行以内にまとめること
- コードの変更を行う際は必ず詳細な説明とrationale（理由）を付記すること

## コミット規則
- コミットは細かく、1機能1コミットを原則とする
- レビューしやすいよう、関連変更はまとめて1コミットにすること

## 言語設定
- コメントは日本語で書くこと
- コードのコメントは英語で記述すること（国際チーム対応のため）

このような矛盾があると、Claudeは一貫性のない応答を返すようになり、チーム内で「なぜこの動作をしたのか」という混乱が生じます。

矛盾を防ぐ「単一責任の原則」の適用

ソフトウェア設計のSOLIDから「単一責任の原則」を借用します。1つのルールは1つの行動だけを規定することを徹底し、相互に影響し合う指示はグルーピングして優先度を明示します。

# ✅ 単一責任で整理されたルール

## 応答スタイル（優先度：MUST）
- コードレビューコメント：1文で要点のみ
- アーキテクチャ説明：背景→選択肢→決定の順で詳述

## コミット規則（優先度：SHOULD）
- バグ修正とリファクタリングは必ず分離する
- 機能追加の場合はテストと実装を同一コミットに含める

アンチパターン③：重複指示（Duplicate Instructions）

重複指示の3つのタイプ

重複指示には以下の3つのタイプがあります。

タイプ	説明	検出難易度
完全重複	まったく同じ内容が複数箇所に存在	低（diffで発見可能）
意味重複	言い回しが異なるが内容は同じ	中（読み比べが必要）
階層重複	グローバルとローカルで同じルールを記述	高（横断的な確認が必要）

意味重複の例：「コードは必ずPEP8に従え」と「Pythonのスタイルガイドに準拠すること」は同じことを言っています。どちらか一方で十分です。

重複指示がもたらす弊害

最も厄介なのが「ゾンビルール」問題です。同じルールがグローバルとローカルの両方に存在するとき、片方だけ更新されると「どちらが正しいのか」が不明な状態が生まれます。古い情報を参照し続けるClaudeは、チームの意図と異なる行動を取り続けます。

重複チェックの実践的な手法

定期クリーンアップにはdiffツールが有効です。グローバルとローカルのCLAUDE.mdを比較し、重複する行を特定します。

# グローバルとローカルのCLAUDE.mdを比較
GLOBAL_CLAUDE="$HOME/.claude/CLAUDE.md"
LOCAL_CLAUDE="./CLAUDE.md"

if [ ! -f "$GLOBAL_CLAUDE" ]; then
  echo "警告: グローバルCLAUDE.mdが存在しません: $GLOBAL_CLAUDE"
fi

if [ ! -f "$LOCAL_CLAUDE" ]; then
  echo "警告: ローカルCLAUDE.mdが存在しません: $LOCAL_CLAUDE"
fi

if [ -f "$GLOBAL_CLAUDE" ] && [ -f "$LOCAL_CLAUDE" ]; then
  diff "$GLOBAL_CLAUDE" "$LOCAL_CLAUDE"
else
  echo "差分比較をスキップ: 一方または両方のファイルが存在しません"
fi

# 意味的な重複確認には、キーワード抽出が有効
FILES_TO_GREP=()
[ -f "$GLOBAL_CLAUDE" ] && FILES_TO_GREP+=("$GLOBAL_CLAUDE")
[ -f "$LOCAL_CLAUDE" ] && FILES_TO_GREP+=("$LOCAL_CLAUDE")

if [ ${#FILES_TO_GREP[@]} -gt 0 ]; then
  grep -n "コミット\|commit" "${FILES_TO_GREP[@]}"
else
  echo "grepをスキップ: 対象ファイルが存在しません"
fi

根本的な解決策として、グローバルとローカルの役割分担を明文化しておくことが重要です。

# ~/.claude/CLAUDE.md の冒頭に記載する
## このファイルの対象範囲
- 対象：全プロジェクト共通のスタイル・コミュニケーション設定
- 対象外：技術スタック固有のルール（→各プロジェクトのCLAUDE.mdに記載）

第3章：「削る」ための優先度付け技術

優先度フレームワーク：インパクト × 頻度マトリクス

段階的に理解を深めていきましょう。削除判断に迷ったとき、「インパクト × 頻度マトリクス」が指針になります。

          高インパクト
               │
    ┌──────────┼──────────┐
    │  圧縮して │  絶対に  │
    │  残す     │  残す    │
低頻度          │          高頻度
    │  即削除   │  要検討  │
    │  の候補   │  ゾーン  │
    └──────────┼──────────┘
               │
          低インパクト

高頻度×高インパクト：コミット規則、言語設定など──絶対に残すコアルール
低頻度×低インパクト：特定のエッジケース向けルール、廃止済みワークフロー──即削除の候補
高頻度×低インパクト：Claudeがデフォルトで行う動作の再指示──削除を検討

「Claudeに言わなくても分かること」を削る

モデルのデフォルト動作を理解することで、不要な明示を大幅に省けます。例えば以下は書く必要がありません。

# ❌ 書く必要のないルール例
- エラーが発生した場合は適切に処理すること
- セキュリティに注意してコードを書くこと
- 変数名は分かりやすいものにすること

これらは「一般常識・業界標準」であり、Claudeはデフォルトで意識しています。CLAUDE.mdに書くべきは、Claudeのデフォルトから外れてほしい点だけです。

ルールの「賞味期限」を設定する

日付コメントによる自動失効の仕組みを導入することで、ゾンビルールの発生を防げます。

## 一時的なルール（開発フェーズ限定）
<!-- 有効期限: 2025-09-30 / レビュー者: @tanaka -->
- α版リリースまではE2Eテストをスキップしてよい
- パフォーマンス最適化は後回しにして機能優先で実装する

フェーズ別にCLAUDE.mdを切り替える戦略も効果的です。

# フェーズ切り替えスクリプト例
SOURCE="CLAUDE.md.production"
DEST="CLAUDE.md"

if [ ! -f "$SOURCE" ]; then
  echo "エラー: コピー元ファイルが存在しません: $SOURCE" >&2
  exit 1
fi

# 既存のCLAUDE.mdをバックアップしてから上書き
if [ -f "$DEST" ]; then
  cp "$DEST" "${DEST}.bak" && echo "バックアップ作成: ${DEST}.bak"
fi

cp "$SOURCE" "$DEST" && echo "本番移行完了: $SOURCE -> $DEST"

削れないルールの「圧縮」技術

どうしても残す必要があるルールは、最小限のトークンで最大の情報を伝える書き方に圧縮します。

# ❌ 冗長な書き方（約80トークン）
コミットメッセージを書く際には、必ず変更の種類を先頭に記載してください。
例えば、新機能の追加であればfeat:、バグ修正であればfix:というプレフィックスを
使用し、その後に簡潔な説明を続けてください。

# ✅ 圧縮した書き方（約20トークン）
コミット: feat:/fix:/docs:/refactor: プレフィックス必須

MUST / SHOULD / MAYによる強度の明示も、Claudeへの伝達精度を上げます。

## コード品質ルール
- MUST: 全パブリック関数にJSDocコメントを付ける
- SHOULD: 処理が3行を超えたら関数に分離する
- MAY: デバッグ用console.logは開発時のみ許容

第4章：CLAUDE.mdのメンテナンス運用設計

「書く前に削る」ワークフローの確立

新しいルールを追加するときに既存ルールを1つ見直す「1追加1見直し」のルールを設けます。これだけでCLAUDE.mdの肥大化を構造的に防げます。

プルリクエストのレビュープロセスにCLAUDE.mdの変更を含めることも重要です。コードの差分と同じように、ルールの変更も「なぜ追加するのか」「何と矛盾しないか」をレビューします。

チーム開発におけるオーナーシップ設計

ファイル	オーナー	変更プロセス
`~/.claude/CLAUDE.md`	各個人	個人の判断で変更可
`プロジェクト/CLAUDE.md`	テックリード	PRレビュー必須
`サブディレクトリ/CLAUDE.md`	担当チーム	チーム内合意で変更可

定期レビューのスケジューリング

スプリント単位での棚卸しが効果的です。以下のチェックリストをスプリントレトロスペクティブに組み込んでみてください。

## CLAUDE.mdスプリントレビューチェック
- [ ] 削除されたライブラリ・APIへの言及はないか
- [ ] 今スプリントの作業で無効化されたルールはないか
- [ ] 矛盾するルールが新たに生まれていないか
- [ ] 「最後にCLAUDE.mdを読んだのはいつか」を全員に確認

第5章：実践サンプル──Before / After で見る改善例

Before：肥大化した典型的なCLAUDE.md

# プロジェクト設定

あなたは優秀なエンジニアです。常に最高品質のコードを書いてください。

## 言語について
- 日本語で応答してください
- コードのコメントは英語で書いてください
- ドキュメントは日本語で書いてください
- コミットメッセージは英語で書いてください
- issueのコメントは日本語で

## コーディングスタイル
- PEP8に準拠すること
- Pythonのスタイルガイドに従ってください（PEP8）
- インデントは4スペース（タブ禁止）
- 変数名は分かりやすく
- 関数名はスネークケース
- クラス名はパスカルケース

## テストについて
- テストを書くこと
- pytestを使用すること
- カバレッジ80%以上を目指すこと
- ※α版期間中はテストを省略してよい
- テストファイルはtest_プレフィックスを付けること

## コミットについて
- 細かくコミットすること
- 関連変更はまとめてコミットすること
- feat: / fix: / docs: プレフィックスを使うこと
- コミットメッセージは50文字以内

## 使用ライブラリ
- Momentjsで日時処理を行うこと（※Day.jsへ移行予定）
- Requestsライブラリを使うこと
- （現在はhttpxを使用中）

## セキュリティ
- SQLインジェクションに気をつけること
- XSSに注意すること
- 適切なエラーハンドリングをすること

## その他
- エラーが発生したら教えてください
- 不明な点は質問してください
- コードは動作するものを書いてください

問題点の整理：

言語ルールが5箇所に分散（意味重複）
コーディングスタイルにPEP8の完全重複
テストルールに矛盾（必須なのか省略可なのか不明）
コミットルールが相反（細かく vs まとめて）
Momentjs（廃止済み）とhttpx（現在使用中）の混在（コンテキスト汚染）
「動作するコードを書け」など当然のことを明示（不要ルール）

After：削って整理されたCLAUDE.md

# プロジェクト設定（最終確認: 2025-07-23）

## 言語（MUST）
- 応答・ドキュメント: 日本語
- コードコメント・コミットメッセージ: 英語

## コード規約（MUST）
- Python: PEP8、スネークケース関数名、パスカルケースクラス名
- HTTP通信: httpxライブラリを使用
- 日時処理: Day.jsを使用

## テスト（MUST / 本番フェーズ）
- pytest使用、test_プレフィックス、カバレッジ80%以上

## コミット（MUST）
- プレフィックス: feat: / fix: / docs: / refactor:
- バグ修正とリファクタリングは必ず別コミット
- メッセージ: 50文字以内

わずか30行以内に圧縮し、矛盾・重複・コンテキスト汚染をすべて解消しました。

削減の判断ログ：何をなぜ消したか

## 削除判断ログ（2025-07-23）

| 削除した内容 | 削除理由 |
|---|---|
| 「優秀なエンジニアです」 | Claudeのペルソナ設定は無効・不要 |
| PEP8の2重記述 | 完全重複 |
| 変数名・クラス名の一般ルール | デフォルト動作と同一 |
| Momentjs言及 | httpxへ移行済み、コンテキスト汚染 |
| 「細かくコミット」vs「まとめて」 | 矛盾ルール、具体的な基準に置換 |
| テスト省略可の注記 | α版終了済み、ゾンビルール |
| セキュリティ一般論 | 業界標準、明示不要 |
| 「エラーを教えて」「質問して」 | Claudeのデフォルト動作と同一 |

まとめ：CLAUDE.mdは「育てる」より「削り続ける」もの

本記事のキーテイクアウェイを3点に絞ります。

コンテキスト汚染・矛盾ルール・重複指示が応答品質を下げる。肥大化したCLAUDE.mdは「書かないより悪い」状態になり得ます。
インパクト × 頻度マトリクスで「残す/削る/圧縮」を判断する。主観的な「必要そう」ではなく、フレームワークに基づいた意思決定が重要です。
定期メンテナンスの仕組みをチームで持つ。CLAUDE.mdはドキュメントと同じく、書いた瞬間から陳腐化が始まります。

今日からできること

まず自分のCLAUDE.mdを開いて「最後に更新したのはいつか」を確認してください。次に、1回のセッションで5行だけ削ることから始めるのをお勧めします。完璧を目指す必要はありません。少しずつ削り続けることが、長期的に最も高いROIをもたらします。

CLAUDE.mdの価値は行数に比例しません。削れば削るほど、残ったルールの影響力は高まります。

付録

CLAUDE.mdクリーンアップチェックリスト

## 追加前チェック
- [ ] このルールは既存のルールと矛盾しないか？
- [ ] 同じ内容がすでに書かれていないか？
- [ ] Claudeのデフォルト動作と同じことを言っていないか？
- [ ] このルールは6ヶ月後も有効か？

## 定期レビューチェック（スプリントごと）
- [ ] 廃止されたライブラリ・ツールへの言及はないか？
- [ ] 矛盾するルールのペアが生まれていないか？
- [ ] グローバルとローカルで同じルールを重複して書いていないか？
- [ ] 有効期限切れの一時ルールが残っていないか？
- [ ] 全チームメンバーが最新のCLAUDE.mdを把握しているか？

## 削除判断基準
- [ ] インパクトが低く、頻度も低い → 即削除
- [ ] Claudeのデフォルトと同じ → 削除
- [ ] 6ヶ月以上更新されていない → 要レビュー

用語集

用語	説明
コンテキストウィンドウ	モデルが一度に処理できるテキストの最大量。トークン数で計測される
システムプロンプト	ユーザーの入力より前に設定される指示。CLAUDE.mdはこれに相当する役割を持つ
トークン	テキストをモデルが処理する際の最小単位。日本語1文字は概ね1〜2トークン
ゾンビルール	かつては有効だったが今は無効・有害になっているにもかかわらず残り続けるルール
コンテキスト汚染	古い・無関係な情報がコンテキストに残り、モデルの判断精度を低下させる現象