CLAUDE.mdの腐敗を防ぐ方法：ルールをコードとして扱う

Claude Codeを本番プロジェクトで18ヶ月間運用した結果、u/mm_cm_m_kmは最も一般的な障害点を特定しました。CLAUDE.mdファイルの腐敗です。Claudeが無視するからではなく、開発者がルールを追加するだけで決してクリーンアップしないからです。結果は、毎ターンにトークンを消費し、実際のコードベースとの同期がずれる、肥大化した500行のファイルです。

1. CLAUDE.mdはマニュアルではなく索引として

CLAUDE.mdは30〜50行に抑えてください。これは、これまで設定したすべての好みの壁ではなく、特定の関心事に対する特定のファイルを指し示す目次として機能するべきです。Claudeは毎ターンこのファイルを再読み込みします。短いファイルはコストが低く、長いファイルはトークンと注意力を無駄にします。

2. 各セクションは2つの質問のうち1つに答える

• どんな振る舞いを望むか？（ルール） — CLAUDE.mdに記載。
• 現在の真実はどこにあるか？（情報源） — タスク時にClaudeが再読み込み可能なフェッチ可能なURLまたはファイルパスとして記載。

ルールと情報源を混在させると、ファイルは無制限に拡大します。ルールは短く、情報源は外部に保ってください。

3. マージ前の監査、マージ後ではない

ルールは、名前の変更、フックのリファクタリング、機能の削除に伴って静かに乖離していきます。解決策は「もっと注意する」ではなく、CIステップです。作者はagentlint（agentlint.net）というGitHubアプリを開発し、すべてのPRでルールサーフェス（ファイル間の矛盾、削除されたパスへの参照、バージョンがサポートしていないハーネス機能を説明するルール）を監査します。

4. 追加よりも削除を優先する

ほとんどのCLAUDE.mdは週に1つルールを追加し、ゼロを削除します。6ヶ月後にはフランケンシュタインのようなファイルになります。規律：新しいルールごとに、1つ削除するものを見つけること。これにより、作者のファイルは100行未満に保たれています。

核となるパターン：ルールサーフェスをコードのように扱うこと。コードにはテスト、レビュー、乖離検出があります。ルールにも同じものが必要です。