コンテキストウィンドウ管理：50セッションから学んだAI開発の教訓

50回のClaude Code開発セッションにわたってトークン消費量を計測しました。パターンは一貫していました。ハードリミットがコンパクションを発動させるよりもはるか前に、コンテキスト使用率が約60%に達した時点で出力品質が劣化し始めます。¹

TL;DR

コンテキストウィンドウの枯渇は、AIコーディングの品質を静かに劣化させます。Claude Codeインフラとブログ品質システムを構築した50セッションを追跡した結果、数時間にわたるセッションで出力品質を維持する3つのパターンを発見しました。サブタスク完了ごとの先回りコンパクション、コンテキスト境界を超えて永続化するファイルシステムベースのメモリ、そしてメインコンテキストをスリムに保つサブエージェント委任です。重要な洞察は、コンテキストウィンドウを底なしの会話スレッドではなく、希少なリソースとして扱うことです。

劣化の実際の姿

ファイル読み込み、ツール出力、会話のターンごとにトークンが消費されます。大きなファイルの読み込み1回（2,000行）で15,000〜20,000トークンを消費することがあります。10個のファイルを読み込み、いくつかのコマンドを実行した後には、コンテキストウィンドウは実際の指示よりもツール出力で占められています。²

劣化は微妙です。Claudeは「コンテキストが80%埋まっています」とは告知しません。代わりに、モデルは以下のような挙動を始めます： - 20分前に設定された指示を忘れる - 3ターン前にすでに却下された提案を繰り返す - 会話の前半で確立されたパターンを見落とす - 複数ファイルにまたがる変更の一貫性が低下する

このパターンに気づいたのは、審議システムを構築しているときでした。8つのPythonモジュールにまたがる精密な複数ファイル編集で始まったセッションが、90分経過時点では単一ファイルへのトンネルビジョンに劣化していました。エージェントは、以前読んだアーキテクチャを参照しなくなっていました。そのコンテキストが圧縮されて消えていたからです。

戦略1：先回りコンパクション

Claude Codeの/compactコマンドは、会話を要約してコンテキスト空間を解放します。システムは重要な決定、ファイル内容、タスクの状態を保持しつつ、冗長なツール出力を破棄します。³

コンパクションのタイミング： - 明確なサブタスクを完了した後（機能実装完了、バグ修正完了） - コードベースの新しい領域に着手する前 - Claudeが以前のコンテキストを繰り返したり忘れ始めたとき

集中的なセッションでは、およそ25〜30分ごとにコンパクションを行っています。審議インフラの構築（9つのPRD、3,455行のPython）では、各PRDの完了後にコンパクションを実行しました。各コンパクションがアーキテクチャ上の決定を保持しつつ、次の実装フェーズのためにコンテキストを解放しました。

戦略2：メモリとしてのファイルシステム

コンテキスト境界を超えて最も信頼できるメモリは、ファイルシステムに存在します。Claude Codeはすべてのセッション開始時とコンパクション後にCLAUDE.mdとメモリファイルを読み込みます。⁴

私の.claude/ディレクトリは、構造化されたマインドパレスとして機能しています：

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

MEMORY.mdファイルは、セッションをまたいでエラー、決定、パターンを記録します。現在、54件の失敗がドメイン横断的な学習パターンとともに記録されています。bashでVARが0のとき((VAR++))がset -eで失敗することを発見したら、記録します。3セッション後、Pythonで似たような整数のエッジケースに遭遇したとき、MEMORY.mdのエントリがそのパターンを呼び起こしてくれます。⁵

ドメイン横断的な複利効果： フック開発時のbashエスケープエラーが、Python製ブログリンターの正規表現改善につながりました。CSSトークンの欠落（--spacing-2xsが存在しない）が、すべてのカスタムプロパティ参照の体系的な監査のきっかけとなりました。各エントリは、個別のセッションコンテキスト内にサイロ化されたままになるはずだったドメイン同士をつなぎます。

戦略3：セッションハンドオフ

複数セッションにまたがるタスクでは、完全な状態を記録するハンドオフドキュメントを作成します：

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

~/.claude/handoffs/ディレクトリには、複数セッションタスクの49件のハンドオフドキュメントがあります。claude -c（続行）で新しいセッションを開始するか、ハンドオフドキュメントを読み込むことで、後続セッションに最小限のトークンコストで完全なコンテキストを提供できます。⁶

ハンドオフパターンは、審議システムの構築中に私を救いました。PRD-4（再帰ガード拡張）では、PRD 1〜3での決定を理解する必要がありました。ハンドオフがなければ、新しいセッションは変更されたすべてのファイルを再読み込みする必要があったでしょう。ハンドオフがあったおかげで、セッションはアーキテクチャのコンテキストを持った状態で始まり、すぐに実装に取りかかれました。

戦略4：サブエージェント委任

サブエージェントは独立したコンテキストウィンドウで実行されます。調査やレビュータスクをサブエージェントに委任することで、メインセッションのコンテキストを実装作業のために保持できます。⁷

私の再帰ガードシステムがこれを自動的に管理します：

# From recursion-guard.sh - spawn budget enforcement
MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

各サブエージェントは生の出力ではなく要約を返すため、メインコンテキストがスリムに保たれます。ブログ記事のリライト中は、探索タスク（CSSデータの収集、フックコードの読み込み、ディレクトリ構造の調査）をサブエージェントに委任しています。メインコンテキストは執筆に集中し、サブエージェントが調査を担当します。

スポーンバジェットは苦い経験から学びました。制限なしの初期セッションで、再帰的なサブエージェントがそれぞれさらにサブエージェントを生成しました。現在、再帰ガードフックが安全な整数バリデーションと設定駆動型のバジェットにより深度制限を強制しています。⁸

学んだアンチパターン

10行だけ必要なのにファイル全体を読み込む。 Claude Codeの使い始めの頃、1つの関数のために2,000行のファイル全体を読み込んでいました。行オフセットを使いましょう：Read file.py offset=100 limit=20で、1回の読み込みあたり15,000以上のトークンを節約できます。

冗長なエラー出力をコンテキストに残す。 スポーンバジェットの問題をデバッグした後、コンテキストには失敗した反復の40以上のスタックトレースが残っていました。バグ修正後に/compactを1回実行するだけで、そのデッドウェイトを解放できました。

毎セッションの開始時にすべてのファイルを読み込む。 最初のセッションでは、「コンテキストのため」に8〜10個のファイルをプリロードしていました。現在はClaude Codeのglobとgrepツールに必要なファイルをオンデマンドで見つけさせており、100,000以上のトークンの不要なプリロードを節約しています。

重要なポイント

個人開発者向け： - Claudeがコンパクションを強制するときではなく、サブタスク完了ごとにコンパクションを実行しましょう。25〜30分間隔の先回りコンパクションが出力品質を維持します - セッションの進行に合わせて、重要な決定をファイルシステムのメモリファイルに書き出しましょう。私のMEMORY.mdには、数百のセッションにわたって永続化される54のエントリがあります - メインコンテキストを汚染する調査タスクにはサブエージェントを使いましょう。5ファイルの調査クエリはメインコンテキストでは75,000以上のトークンを消費しますが、サブエージェント経由なら500トークンの要約で済みます

チーム向け： - 複数セッションタスクのためにハンドオフドキュメントのフォーマットを標準化しましょう。私の49件のハンドオフは、すべてStatus/Files/Decision/Blocked/Nextの同じ構造に従っています - すべてのセッションに自動的に読み込まれるアーキテクチャコンテキストを、プロジェクトレベルのCLAUDE.mdファイルに設定しましょう

参考文献