9月27日、Abhijith N Arjunanが「I cut my CLAUDE.md in half and Claude Code stopped fighting itself」と題した記事を公開した。CLAUDE.mdに書いたルールが多いほどClaude Codeは賢くなる——そう信じて指示を書き足してきた筆者が、逆に「半分に削ることで安定した」と報告している。原因は情報量の多さではなく、指示同士が互いに干渉し、会話が進むほどじわじわと精度を蝕むという構造的な問題だった。
CLAUDE.mdは「全メッセージに課される税金」だ
Claude Codeでは、プロジェクトルートに置いたCLAUDE.mdがモデルへの常設指示として機能する。使い込むほど、プロジェクトの慣習・出力フォーマット・文体ルールなど追記したいものが増え、ファイルが自然と肥大化していく。
しかしこのファイルには根本的な制約がある。Claude CodeはすべてのメッセージでCLAUDE.mdを無条件にロードする。コード補完の依頼でも、文書の校正依頼でも、ファイルの中身が丸ごとコンテキストウィンドウに乗る。ルールの適用範囲をタスクごとに絞る仕組みは存在しない。
コンテキストウィンドウとは、モデルが一度に参照できるテキストの総量（トークン数）のことだ。CLAUDE.mdが長くなるほど、この有限のリソースを毎回消費することになる。まさに毎回のメッセージに自動で課される「税金」であり、ファイルが重くなるほど税率が上がる構造だ。
実害は2点ある。
- トークン消費の増大：ファイルが長いほど、毎回のやり取りで余分なトークンを消費し、実質的なコンテキスト上限を圧迫する
- 指示同士の競合：複数のルールがコンテキスト上で「注意を奪い合い」、会話が長引くほどモデルの一貫性が落ちる
問題の本質は「情報過多」ではなく「指示の競合」
筆者が最初に立てた仮説は「長いCLAUDE.mdはモデルを混乱させる」というものだった。しかし実際は少し異なる。複数の指示が互いに干渉することで、Claude Codeが自滅していたのだ。
具体例が明快だ。筆者はかつて出力にem dash（—）を使わないよう指示をCLAUDE.mdに書いた。その後、「anti-AI writing rules」（AIが生成した文章特有の言い回しを排除するためのスタイルルール群）という別セクションを追加し、同じ内容を別の言葉で繰り返した。この2つの記述がコンテキスト上で注意を奪い合い、長い会話の10〜15ターン目あたりから、禁止したはずのem dashが出力に混入するようになったという。
繰り返しはルールを強化しない。むしろClaude Codeを圧迫する。
さらに、CLAUDE.mdの指示は他のシステムプロンプトとも競合する。ターン数が増えるほどその影響が蓄積されるため、「突然壊れる」のではなく、じわじわと精度が落ちていくという形の劣化として現れる。これが発見しづらい原因でもある。
解決策：Audit my CLAUDE.md の一言
改善の手順はシンプルだった。Claude Code自身にCLAUDE.mdを監査させたのだ。
Audit my CLAUDE.md
このコマンドを投げるだけで、Claude Codeは冗長な記述・重複したルール・不要なセクションを詳細にレポートした。その後、筆者は手動で編集するのではなく、Claude Code自身に修正を依頼した。
Claude Codeが実施した主な変更は以下の通りだ：
- 重複した記述を統合・削除
- 文体ルールを
writing-style.mdとして別ファイルに分離（コーディング作業時にはロードされない） - 空のプレースホルダーを追加し、後で補足できる構造を整備
結果としてCLAUDE.mdは約半分の長さになり、特にマルチターンの会話でのパフォーマンスが改善したという。
CLAUDE.mdに書くべきことの線引き
この経験から導き出される判断基準はシンプルだ。Claude Code全体に常時適用されるべきルールだけをCLAUDE.mdに残すということだ。特定タスク（文書生成・スライド作成など）に限定される指示は、別ファイルに切り出すかプロンプト側に移すべきで、具体的には以下のように整理できる。
CLAUDE.mdに残すもの：プロジェクト全体で常に有効であるべきルール（コードの命名規則、コミットメッセージの形式など）- 別ファイルに分離するもの：特定タスクにのみ関係するルール（文体・スタイルガイドラインなど）
- プロンプト側に移すもの：単発・一時的な指示
ただし筆者は「誰にでも通用する万能解ではない」とも述べている。自分のCLAUDE.mdがどう使われているかを把握した上でのファイル設計が必要であり、監査はなるべく早い段階で実施するのがよい。肥大化を放置するほどトークンコストが積み上がり、精度の劣化も静かに進行する。
詳細はI cut my CLAUDE.md in half and Claude Code stopped fighting itselfを参照していただきたい。
