CLAUDE.md肥大化問題：AIエージェント指示書が52Kを超えたときの対処法

Claude Codeを本格運用していると、プロジェクトの指示書であるCLAUDE.mdが際限なく肥大化する問題に直面します。筆者のプロジェクトでは52,200文字（約95KB）に達し、パフォーマンス警告 Large CLAUDE.md will impact performance (52.2k chars > 40.0k) が表示されるようになりました。この記事では、CLAUDE.mdがなぜ膨らむのか、どこまで削れるのか、実際に52K → 29Kに圧縮した手順を具体的に解説します。

なぜCLAUDE.mdは膨らむのか

CLAUDE.mdの肥大化には構造的な原因があります。

1. 教訓の蓄積

障害が起きるたびに再発防止策をCLAUDE.mdに追記する運用は、AI駆動開発では自然な流れです。「同じミスを二度させない」ために教訓を書き残します。問題は、2週間で20件のインシデントが発生すれば20個のルールが追加されるということです。

筆者のプロジェクトでは、Critical Rulesが20個に達し、それぞれに教訓のblockquoteが付いて329行（CLAUDE.md全体の53%）を占めていました。

2. @参照ファイルの積み重ね

Claude Codeでは@ファイル名でCLAUDE.mdから外部ファイルを参照できます。便利ですが、フレームワーク系のファイルを13個参照した結果、76.4KBが毎回ロードされていました。

3. チェックリストの膨張

デプロイ前チェックリストが29項目、よくあるエラーパターンが20件以上。一つひとつは必要に見えますが、合計するとCLAUDE.mdの大部分を占めます。

パフォーマンスへの影響

CLAUDE.mdが大きいと何が起きるのでしょうか。

• コンテキストウィンドウの圧迫: 毎回の会話開始時にCLAUDE.md全文がロードされます。52K文字が毎回消費されると、実際の作業に使えるコンテキストが減ります
• 応答速度の低下: 入力トークンが増えるため、最初の応答までの時間が長くなります
• ルール遵守率の低下: 皮肉なことに、ルールが増えすぎるとAIはルールを守れなくなります。重要なルールが大量のテキストに埋もれてしまいます

圧縮の実践 — 52K → 29Kへの道のり

Step 1: 現状分析 — 何がどれだけ読み込まれているか把握する

まず、CLAUDE.md起動時に何が読み込まれるかを分解します。

@参照が全体の80%を占めていることが一目でわかりました。

Step 2: @参照を厳選する（76KB → 24KB、-68%）

13個の@参照ファイルのうち、毎回必要なものと呼ばれたときだけ必要なものを分類しました。

残した3ファイル（24.2KB）:

• FLAGS.md（5.5KB）— フラグ定義。毎回参照される
• PRINCIPLES.md（2.6KB）— 設計原則。判断基準として常に必要
• RULES.md（16.1KB）— コーディングルール。コード生成時に必須

外した10ファイル（52.2KB）:

• MODE_Business_Panel.md, MODE_Task_Management.md, MODE_Orchestration.md 等

これらはスキル（/sc:business-panel等）呼び出し時にスキル側が直接Readで読むため、@参照で事前ロードする必要がありませんでした。

判断基準: 「スキルやツール経由で必要なときだけ読めるファイルは@参照しない」

Step 3: プロジェクトCLAUDE.mdを圧縮する（726行 → 198行、-73%）

教訓付きのCritical Rulesが最大の膨張要因でした。

Before:

1
### Critical Rule #7: 日時比較は日またぎを考慮する
2
datetime.time()の比較は日またぎで無効化される...
3

4
> **教訓（2026-04-08）**: JSプロセスが24時間以上継続しゾンビ化。
5
> メインループ内で `datetime.now().time() >= time(15,30)` と比較していたが、
6
> 日をまたぐと15:30は翌日の15:30まで到達せず...（以下30行の詳細）

After:

1
### Critical Rule #7: 日時比較は日またぎを考慮する
2
datetime.time()の比較は日またぎで無効化される。
3
→ 詳細: .claude/docs/CLAUDE_11_CRITICAL_RULES_DETAILS.md

教訓の本文を .claude/docs/ 配下の分離ファイルに退避し、CLAUDE.mdにはルール本文と参照先だけを残しました。

Step 4: グローバルCLAUDE.mdを圧縮する（377行 → 96行、-75%）

施策ワークフローの詳細手順（147行）を memory/measure_workflow_details.md に分離し、骨格（18行）だけ残しました。Post-Implementation QA（82行）も10行の骨格に圧縮しました。

Step 5: MEMORY.mdを整理する（248行 → 51行）

MEMORY.mdはインデックスファイルですが、200行を超えると切り捨てられます。詳細な知識を分離ファイルに退避し、1行1エントリのインデックスに戻しました。

最終結果

40Kの警告閾値をクリアし、パフォーマンス警告は解消されました。

設計原則 — 「毎回必要か？」で判断する

圧縮作業を通じて見えてきた原則をまとめます。

1. CLAUDE.mdには「毎回必要な情報」だけ残す

• Build/Testコマンド
• アーキテクチャ概要
• Critical Rules（本文のみ、教訓は分離）
• API仕様の要点

2. 「必要になったら読む」方式を活用する

Phase詳細、コード例、過去の障害記録などは .docs/ に退避し、AIが必要に応じてReadツールで参照します。CLAUDE.mdに「→ 詳細: .docs/xxx.md」と参照先だけ書いておきます。

3. @参照は「スキル経由で読めないもの」だけ

スキルやツール呼び出し時に自動で読み込まれるファイルは、@参照で事前ロードする必要がありません。

4. ルールは数より「守れる形」

20個のルールを並べるより、5個の明確なルールの方がAIの遵守率は高くなります。ルールが増えたら統合・階層化を検討しましょう。

まとめ

CLAUDE.mdの肥大化は、AI駆動開発を真剣に運用すれば必ず直面する問題です。教訓を蓄積するのは正しいですが、蓄積の仕方を間違えるとAIのパフォーマンスとルール遵守率の両方が下がります。

「毎回ロードすべきか、必要なときに読めばよいか」 — この判断基準で情報を分離するだけで、CLAUDE.mdは半分以下にできます。定期的に棚卸しの時間を取ることをお勧めします。