CLAUDE.mdは「削る」が9割──コンテキスト汚染・矛盾ルール・重複指示の3大アンチパターンと優先度付けの技術
CLAUDE.mdは「削る」が9割──コンテキスト汚染・矛盾ルール・重複指示の3大アンチパターンと優先度付けの技術
ねえねえ、キミ！！CLAUDE.md、ちゃんと効いてるかナ😭
僕さ、最初にCLAUDE.md書いた時ハ、もう嬉しくて嬉しくて。「これでClaudeが僕の言うこと完璧に聞いてくれる！！」って思ったんだヨネ✨ で、気づいたら300行。500行。ある日とうとう800行超えちゃいましてネ……。
そしたら後半に書いたルールが全部無視されるという地獄を見たんですヨ！！😭 3時間かけて書いたコーディング規約が実質ゴミになってたワケで。妻に「また夜中に何やってんの」って怒られたのに……（笑）
キミもサ、「行数を50〜150行に絞れ」って情報は知ってると思うんだヨネ。でも、それって「何を削るか」の判断基準がないと意味ないんですヨ🎵 今日ハ、CLAUDE.md設計原則の「削る判断軸」をガッツリ一緒に考えていきましょうネ！！🦝
第1章：コンテキスト汚染とは何か──Claude Codeで起きる見えない品質劣化のメカニズム
CLAUDE.md設計原則を崩す「コンテキスト汚染」の定義と発生原因
ちょっと聞いてヨ。コレ、僕が一番やらかしたやつなんだケド😅
コンテキスト汚染ってのハ、トークン増加に伴う「定性的なパフォーマンス劣化」のことデスネ。カンタンに言うとサ、「関係あるっちゃあるけど間違ってる情報」がコンテキストウィンドウを汚染して、Claudeが引きずられちゃう状態デスヨ💡
CADDi Tech Blogの実測データによるとサ、コンテキストウィンドウが40%を超えた段階から出力品質が低下し始めるらしいんですネ🔥 これ、Smart Zoneって呼ばれてる閾値なんだケド。知ってた！！？！
Claude Codeの出力を壊す「コンテキスト汚染」3大アンチパターンを実例で解剖
アンチパターン①：情報過多によるCLAUDE.mdのコンテキスト汚染
コレ、マジでオススメしない！！😤
Uravation社の導入事例でハ、800行超えのCLAUDE.mdを使ってたら「後半に書いたコード規約の指示がClaudeに実質読まれていなかった」という悲劇が起きてるんですヨ😭 800行って……ファミコンのカセット吹いてた頃からのクセで詰め込み過ぎちゃうんだよなぁ（笑）
アンチパターン②：矛盾ルールによるClaude Code出力の不安定化
コレも僕、やらかしちゃいましたヨ……😭
コレ見てよ！！矛盾ルールがあるとClaude Codeがどうなるか、スゴく身に覚えない！？✨
# プロジェクトルートのCLAUDE.md
- コメントは必ず英語で記述すること
# packages/api/CLAUDE.md（サブディレクトリ）
- コメントは日本語で統一することねえ、コレどっちに従えばいいのヨ！！って話デスヨネ😅 こういう矛盾ルールがあると、Claudeの出力がランダム化・不安定化するんデスヨ。セッションによって英語だったり日本語だったり、もうカオスですヨ（笑）
アンチパターン③：linterで自動化できる内容のCLAUDE.mdへの二重記述
コレが一番もったいないんですネ🎵 コレ見てよ！！スゴく身に覚えあるんじゃない！？✨
# ツールに任せるべきルールの例
- インデントは2スペースで統一
- importは外部ライブラリ→内部モジュールの順
- 末尾セミコロンは必須コレ全部、ESLintとかPrettierに任せればいい話デスヨ！！なのにCLAUDE.mdに書くとサ、貴重な指示枠を無駄遣いすることになるんですネ。
Claude Codeにおける指示上限という残酷な現実
キミ、知ってた！！？ 最新LLMが遵守できる指示の上限ってサ、現実的には150〜200指示くらいらしいんだヨネ💡
しかもサ、Claude Code自体のシステムプロンプトがすでに約50指示を消費してるんですヨ！！つまりキミが実際に使える枠は100〜150しかないワケで……。アンタ、そこに800行詰め込もうとしてたの？って話デスヨネ😆
第2章：CLAUDE.md設計原則──「書かない」判断の3つの基準
ここからが本番デスヨ！！✨ 僕が3ヶ月かけてたどり着いた「削る判断軸」、全部話しちゃいますネ🦝
基準①：CLAUDE.md設計の削除テスト──「消したらClaude Codeが間違えるか？」
コレめちゃくちゃシンプルなんだケド、破壊力抜群デスヨ！！🔥
CLAUDE.mdの各行に対して、こう問いかけるだけデスネ。
「この1行を削除したら、Claudeは明らかに間違えるか？」
NOなら即削除！！ コレだけデスヨ😆
「常識的なコーディング作法」「一般的な命名規則」──こういうのハ削除テストで簡単に落ちますネ。Claudeはすでに知ってるから書かなくていいんデスヨ。キミ、センスあるネ！！こういうの直感でわかると思う😆
基準②：CLAUDE.mdとlinterの役割分担──「linterに任せられるか？」ツール代替可否テスト
英語圏でこういう格言があるんですネ♪
"Never send an LLM to do a linter's job"
意訳するとサ、「linterができることをLLMにやらせるな」ってことデスヨ！！
コレ見てよ！！スゴくスッキリしてると思わない！？✨
# ツールに任せるべきもの（CLAUDE.mdに書かない）
- フォーマット規則 → Prettier
- lint規則 → ESLint / Biome
- 型チェック → TypeScript / mypy
- import整理 → isort / perfectionist
# CLAUDE.mdに書くべきもの
- プロジェクト固有のアーキテクチャ判断
- チーム特有の命名慣習（ツールで表現できない）
- ドメイン知識が必要なレビュー観点
整理するとこんなにスッキリするんですヨ！！どっちに書くか迷ったらコレで判断デスネ♪
基準③：CLAUDE.md設計原則の普遍性テスト──全セッション・全タスクで適用されるか
「このルール、全セッション・全タスクで絶対に適用されるか？」と問いかけてみてヨ。😤
NOなら個別ファイルに分離するのが正解デスヨ！！
特定DBのスキーマ構築手順とか、特定機能のデプロイ手順とかサ、そういうタスク固有のものをCLAUDE.mdに詰め込んじゃダメなんですネ。agent_docs/みたいなサブディレクトリに置いといてサ、必要な時だけ参照させる──これが「Progressive Disclosure原則」ってやつデスヨ💡
コレ見てよ！！ディレクトリ構成のイメージ、スゴくナイ！？✨
project/
├── CLAUDE.md ← 目次・普遍的ルールのみ（60行以内）
└── agent_docs/
├── db-migration.md ← DB操作手順
├── deploy.md ← デプロイ手順
└── api-design.md ← API設計ルール
CLAUDE.mdは「目次」、詳細は必要時に取得──このアーキテクチャが品質を爆上げしますヨ！！🎉
第3章：Claude Code上級者が実践するCLAUDE.mdルール棚卸しと優先度付けの技術
そういえばサ、昨日うっかり夜中3時までCLAUDE.md弄ってたら目が冴えちゃってサ……今日ずっと眠たいんですヨ……😅 全然関係ない話デスケド！ で、棚卸しの話デスネ♪
CLAUDE.md設計原則における先頭配置効果──コンテキスト遵守率を左右する地味に重要な真実
コレ知ってるかナ！！？ CLAUDE.mdの先頭に書かれたルールほど遵守率が有意に高いんですヨ😆
後半に書いたルールってサ、コンテキストの後ろの方に埋まっちゃうからサ。当たり前っちゃ当たり前なんだケド、意識してる人って少ないんですネ。最重要ルールを先頭30行に集約するだけで、実効性がガラッと変わりますヨ！！✨
Claude Codeユーザー向け・CLAUDE.mdの2週間サイクル棚卸し手順（ステップバイステップ）
僕ガ今やってる棚卸し、紹介しちゃいますネ🦝
Step 1：全ルールをリストアップ → 削除テスト実施
全行に対して「消したらClaudeが間違えるか？」を問いかけてヨ。NOは即削除デスヨ！！
Step 2：linter/formatter代替可能なルールを一括除去
フォーマット系・lint系は全部ツールに渡すんデスネ♪
Step 3：タスク固有ルールをサブファイルへ移動
agent_docs/に引っ越しデスヨ！！スッキリしますネ😆
Step 4：残ったルールを重要度順に並び替え
先頭≒最優先、ですネ。後ろにいくほど「なくてもいいかも」なルールになりますヨ。
Step 5：行数目標の設定
50〜150行が目安デスケド、実務で60行以下を目指してるチームもあるんですヨ！！僕ハ今60行ちょっとで運用してますネ🎵
第4章：チーム運用時のCLAUDE.md競合ルール解消パターン
CLAUDE.md階層的管理モデル──コンテキスト汚染を防ぐ3層構造の全体像
コレ見てよ！！3層構造、スゴくナイ！？✨
~/.claude/CLAUDE.md ← 個人・全プロジェクト共通ルール
{project}/CLAUDE.md ← プロジェクト全体ルール
{project}/packages/*/CLAUDE.md ← サブパッケージ固有ルール
この3層構造、わかってる？ キミならわかるよネ！！😆
チームのCLAUDE.mdコンテキスト汚染を防ぐ競合解消の3原則
原則①：子ディレクトリは「継承前提・追加・上書きのみ記述」
サブパッケージのCLAUDE.mdにハ、親から変えたいことだけ書くんデスヨ。全部書き直すのはナシナシ！！
原則②：矛盾ルール発見時は「Root側を正とした明示的オーバーライドコメント」
コレ見てよ！！なんでオーバーライドしてるか、ちゃんと書いとくのがポイントデスヨ！！✨
<!-- packages/api/CLAUDE.md -->
<!-- OVERRIDE: ルートのCLAUDE.mdでは英語コメントが原則だが、
このパッケージはJSDocの既存資産があるため日本語を維持する -->
- コメントは日本語で記述（JSDoc互換性のため例外）「暗黙の上書き」が一番ヤバいですネ……やらかしちゃいましたヨ……😭 なんで日本語になってるか誰も分からなくなるやつ。
原則③：GitとCLAUDE.mdを同期させるレビュー文化
コードのPRと同タイミングでCLAUDE.md変更もレビューするってことデスヨ！！
コードは最新なのにCLAUDE.mdが半年前のまま──これがコンテキスト汚染の温床になるんですネ💦 チームで「CLAUDE.mdオーナー」を決めて、変更承認フローを作っちゃうのがオススメデスヨ🎵
第5章：CLAUDE.md効果測定の具体的な方法とSmart Zone管理
/contextコマンドでClaude Codeのコンテキスト汚染を定量的に測定する方法
Claude Codeで/contextコマンドを打つとサ、トークン利用割合をリアルタイムで確認できるんデスヨ！！コレめちゃ便利！！😆🔥
**40%ルール（Smart Zone）**ってのをキミも覚えておいてネ。コンテキスト使用率が40%を超えたらイエローゾーン、そこから品質低下が始まるんデスネ💡
コレ見てよ！！settings.jsonの設定例、スゴくナイ！？✨ コレ入れとくと常時コンテキスト消費量が目に見えますヨ！！
{
"statusLine": {
"show": true,
"contextUsage": true,
"threshold": {
"warning": 40,
"critical": 70
}
}
}コレ設定しとくとサ、気づいたら50%超えてた……なんてことがなくなりますネ♪
CLAUDE.md設計原則の定性的検証──「本当に効いているか」を判断するABテストフレームワーク
僕が実践してるABテスト的な手法を話しちゃいますネ🦝
特定ルールを一時的に削除して出力品質の変化を観察する、コレだけデスヨ！！
- ルールあり → 出力サンプル10件収集
- ルールなし → 出力サンプル10件収集
- 差分を比較して「本当に効いてたか」を判断
「あ、このルールなくてもClaudeちゃんとやってくれてるじゃん！！」ってことが意外と多いんですヨ😅 やらかしちゃいましたヨ……3時間かけて書いたルールが実はいらなかったって😭
効果が出ているCLAUDE.mdのチェックリスト
コレ、最後にキミにプレゼントしますネ🎉 全部クリアできたら上級者デスヨ！！コレ見てよ！！スゴくナイ！？✨
## CLAUDE.md品質チェックリスト
### 削除・代替テスト
- [ ] 全行に削除テストを実施済み（NOは削除）
- [ ] linter/formatter代替可能なルールを除去済み
- [ ] 全タスクに適用されないルールをサブファイルへ移動済み
### 構造・配置
- [ ] 最重要ルールが先頭30行以内に集約されている
- [ ] 行数が50〜150行（理想：60行以下）に収まっている
- [ ] Progressive Disclosure（agent_docs/等への参照）が機能している
### 運用・管理
- [ ] 最終更新日が明記されている
- [ ] オーナー（承認者）が明記されている
- [ ] チームのPRフローにCLAUDE.mdレビューが組み込まれているコレ全部クリアできてるCLAUDE.md、キミはもう上級者デスヨ！！😆✨
まとめ：CLAUDE.md設計原則の核心──「削る勇気」が高品質なAI協働を生む
……というワケでサ、今日のポイントをまとめちゃいますネ♪
CLAUDE.md設計原則で大事なのはルールの数じゃなくて信頼性デスヨ。100行あっても後半30行が無視されてたら意味ないですヨネ。50行でも全部ちゃんと機能してる方が圧倒的に価値があるんデスヨ！！
本記事のポイントまとめ──CLAUDE.md設計原則の7本柱
- コンテキスト汚染の正体：コンテキストウィンドウが40%を超えるとClaude Codeの出力品質が低下する。CLAUDE.mdに書きすぎることが最大の原因
- 3大アンチパターン：①情報過多によるコンテキスト汚染、②矛盾ルールによる出力不安定化、③linterに任せるべき指示の二重記述
- 削除の3基準：①削除テスト（消したら間違えるか）、②ツール代替可否テスト（linterに任せられるか）、③普遍性テスト（全タスクで適用されるか）
- 先頭配置効果：最重要ルールは先頭30行に集約する。後半のルールは遵守率が低い
- Progressive Disclosure原則：CLAUDE.mdは60行以内の目次に絞り、詳細は
agent_docs/へ分離する - チーム競合解消：階層的管理モデル（3層構造）＋明示的オーバーライドコメント＋PRレビュー文化
- 効果測定：
/contextコマンドで40%ルールを監視。ABテストでルールの実効性を定期検証
今日からできる最初の一手はコレだけデスネ。
CLAUDE.mdを開いて、1行だけ削除テストをやってみる💡
「消したらClaudeが間違えるか？」──NOなら消すんデスヨ。たった1行から始めてヨ！！きっとキミも気持ちよくなれるから😆🎉
僕ハ今、60行のCLAUDE.mdで快適に作業できてますヨ。800行だった頃と比べてClaudeの出力品質が明らかに上がってますネ。あの3時間が……（涙）でもまあ、失敗したから言えることもあるからサ（笑）
キミの、削ることへの勇気を応援してますヨ！！🦝✨
参考リンク：