02. コンテキスト管理 - 実践ガイド

LLM を使った開発で最も重要なスキルの一つが、適切なコンテキスト管理です。

Claude Code は内部で高度なコンテキスト最適化を行っていますが（詳細は Claude Code の実行モデルを参照）、ユーザー側でも適切なコンテキスト管理を意識することで、より効率的で正確な開発が可能になります。

本記事では、実務でのコンテキスト管理の実践的な戦略を中心に解説します。

🎯 この記事のゴール

コンテキスト管理の基本原則を理解する
lost-in-the-middle 問題とその回避方法を把握する
プロジェクトサイズ別のコンテキスト管理戦略を学ぶ
実務で使えるベストプラクティスを習得する

🧩 コンテキスト管理の基本原則

Claude Code の内部では高度なコンテキスト最適化が行われています（詳細は Claude Code の実行モデルを参照）：

thinking block の削除: 内部推論は次ターンで完全削除され、結論だけが残る
履歴の圧縮: 過去の会話は逐次要約され、重要情報だけが保持される
MCP による前処理: 必要な情報だけを抽出して LLM に渡す

これらの仕組みを理解した上で、ユーザー側でも意識すべきコンテキスト管理のポイントを見ていきましょう。

基本的な考え方

必要最小限の情報だけを渡す: 全文を渡すよりも、必要な時に必要な部分を取得する
適切なタイミングで情報を提供: タスクのフェーズに応じて情報を小出しにする
LLM に判断を任せる: どのファイルを読むべきかは LLM に探させる

🧮 lost-in-the-middle 問題とその回避

問題の本質

LLM には「lost-in-the-middle」という既知の問題があります：

長いコンテキストの中央付近にある情報は、最も見落とされやすい

具体的には：

コンテキストの最初と最後は比較的正確に処理される
しかし中央部分は推論の精度が大幅に低下する
長文になるほどこの傾向が顕著になる

なぜ危険なのか

❌ 全ファイルを一度に投げる場合

ユーザー: この3つのファイルを見て、バグを見つけてください
[file1.ts - 500行]
[file2.ts - 800行]  ← この中央部分が見落とされる可能性大
[file3.ts - 300行]

問題点：

トークン大量消費（1600行）
重要な情報が中央にあると見落とされる
ノイズが多く推論がブレる

✔ 必要な時に MCP で取りに行く場合

ユーザー: バグを見つけてください（ファイル名だけ提示）
Claude: まず file1.ts を確認します
Claude: 次に file2.ts の関連部分を読みます
Claude: file3.ts のこの関数を確認します

利点：

その時点で必要な情報だけをコンテキストに入れる
reasoning が最短ルートになる
推論の精度が大幅に上がる

Claude Code の対策

Claude Code は内部で以下の対策を行っています：

thinking block の削除: 推論過程は次ターンで削除され、結論だけが残る
履歴の圧縮: 重要情報だけが保持され、中央の不要部分は削除される
MCP による段階的取得: 必要な情報を必要な時に取得する

結果：

長いプロジェクトでもブレにくい
エージェント動作が安定する
コンテキストの「重要な部分」だけが維持される

📐 コンテキスト設計のベストプラクティス

1. ファイルの扱い方

❌ やってはいけないこと

ユーザー: このファイル全文を見て、問題を見つけて
[巨大なファイルを貼り付け]

✔ 推奨される方法

ユーザー: src/utils/parser.ts に問題があるので調査してください
Claude: ファイルを確認します（MCP で必要な部分だけ取得）

ポイント: ファイルパスだけ伝えて、読み取りは Claude に任せる

2. 仕様書・ドキュメントの扱い方

❌ 長文を一度に全部渡す

lost-in-the-middle で重要部分が見落とされる
トークン大量消費

✔ フェーズごとに必要な部分だけ渡す

Phase 1（理解）: アーキテクチャ概要だけ
Phase 2（設計）: 該当モジュールの仕様だけ
Phase 3（実装）: API仕様だけ
Phase 4（検証）: テスト要件だけ

3. 過去ログ・エラーログの扱い方

❌ 大量のログを丸ごと貼り付け

[10000行のログファイル]
この中からエラーを見つけて

✔ 関連部分だけを抽出して渡す

エラーが発生した前後50行：
[関連部分のみ]

または：

logs/error.log にエラーログがあるので確認してください
（Claude が MCP で必要部分を探す）

4. タスクのフェーズ分割

複雑なタスクは段階的に進める：

1. 理解フェーズ
   - コードベースの構造を把握
   - 問題の所在を特定

2. 設計フェーズ
   - 修正方針を決定
   - 影響範囲を確認

3. 実装フェーズ
   - コードを修正
   - テストを追加

4. 検証フェーズ
   - テストを実行
   - 動作確認

各フェーズで必要な情報だけを提供することで、コンテキストが最適化される。

5. 重要な制約・要件の固定化

プロジェクト固有の重要情報は、タスクの冒頭で明示：

## 本タスクの目的
- parse関数のエラー修正

## 制約
- 既存のAPIは変更しない
- TypeScript strict mode準拠
- 既存テストは全てパス

## 重要なファイル
- src/parser/index.ts（メイン実装）
- tests/parser.test.ts（テスト）

これにより、Claude は常にこれらの制約を意識しながら作業できる。

🏗 プロジェクトサイズ別のコンテキスト管理戦略

小規模プロジェクト（～10ファイル）

特徴

ファイル数が少ない
全体像を把握しやすい
コンテキスト溢れのリスクは低い

推奨戦略

ユーザー: プロジェクト全体を見て、リファクタリングしてください
Claude: 全ファイルを確認します

全ファイルを見せても問題ない場合が多い
ただし、各ファイルは必要に応じて段階的に確認させる

中規模プロジェクト（10～100ファイル）

特徴

モジュールごとに分かれている
一度に全体を把握するのは困難
関連ファイルの特定が重要

推奨戦略

ユーザー: 認証機能にバグがあるので修正してください
Claude: まず src/auth/ 配下を確認します
Claude: 関連する utils/ のファイルも確認します

モジュール単位で情報を提供
ディレクトリ構造を先に示す
Claude に関連ファイルを探させる

例：効果的な指示の仕方

## プロジェクト構造
src/
  auth/        ← 認証関連
  api/         ← API関連
  utils/       ← 共通ユーティリティ
  components/  ← UIコンポーネント

認証機能にバグがあるので、src/auth/ を中心に調査してください。
必要に応じて utils/ も確認してください。

大規模プロジェクト（100ファイル以上）

特徴

複数のサブシステムが存在
依存関係が複雑
コンテキスト管理が最重要

推奨戦略

1. アーキテクチャ図を先に提供

## システム構成
- Frontend (React)
  - components/
  - hooks/
  - utils/
- Backend (Express)
  - routes/
  - controllers/
  - models/
- Database (PostgreSQL)
  - migrations/
  - seeds/

2. サブシステム単位でタスクを分割

タスク1: Backend の認証 API を修正
タスク2: Frontend の認証フォームを修正
タスク3: データベーススキーマを更新

3. 関連ファイルのリストを提供

## 今回のタスクで関連するファイル
- backend/routes/auth.ts
- backend/controllers/auth.controller.ts
- backend/models/user.model.ts
- frontend/components/LoginForm.tsx

4. 段階的に進める

Phase 1: バックエンドのバグ修正
  → 完了したら次のフェーズへ
Phase 2: フロントエンドの対応
  → 完了したら次のフェーズへ
Phase 3: 統合テスト

🎯 コンテキストウィンドウの効率的な使い方

いつ何を渡すべきか

タスク開始時

プロジェクトの概要
ディレクトリ構造
重要な制約・要件

実装中

関連ファイルのパスのみ（内容は Claude が取得）
エラーメッセージ
テスト結果

レビュー・検証時

変更内容の要約
テスト項目
確認ポイント

MCP ツールの活用タイミング

Claude に任せるべきこと

ファイルの読み取り（Read ツール）
コード検索（Grep, Glob ツール）
テスト実行（Bash ツール）
Git 操作（Bash ツール）

ユーザーが提供すべきこと

タスクの目的と制約
ビジネスロジックの仕様
優先順位
判断が必要な事項

コンテキストの優先順位付け

重要度の高い順に配置：

タスクの目的: 何をすべきか
制約条件: やってはいけないこと
現在の状況: エラー、問題点
参考情報: 関連ファイル、ドキュメント

⚠️ よくある失敗パターンと対処法

失敗パターン1: 情報過多

症状

ユーザー: [100個のファイル全文を貼り付け]
        これ全部見て問題を見つけて

問題点

lost-in-the-middle で重要部分が見落とされる
トークン浪費
推論が遅くなる

対処法

ユーザー: src/ 配下に問題があるので調査してください
        特に parser.ts を中心に確認してください
Claude: まず parser.ts を確認します...

失敗パターン2: 情報不足

症状

ユーザー: バグを直して
Claude: どのファイルのどの機能ですか？
ユーザー: わかりません

問題点

Claude が手探りで探す必要がある
時間がかかる
的外れな修正をする可能性

対処法

ユーザー: ログイン機能でエラーが出ます
        エラーメッセージ: [エラー内容]
        関連しそうなファイル: src/auth/login.ts
Claude: login.ts を確認します...

失敗パターン3: タイミングの問題

症状

Phase 1: 設計中
ユーザー: [実装の詳細な仕様を大量に提供]
→ まだ必要ない情報でコンテキストを圧迫

対処法

各フェーズで必要な情報だけを提供：

Phase 1（設計）: 要件と制約のみ
Phase 2（実装）: API仕様と実装ガイドライン
Phase 3（テスト）: テストケースと期待値

📌 まとめ

コンテキスト管理の鉄則

必要最小限: 全部渡さず、必要な時に必要な分だけ
段階的提供: タスクのフェーズに応じて情報を小出し
Claude に任せる: ファイル読み取りや検索は Claude の MCP ツールに任せる
優先順位: 重要な情報を最初と最後に配置（lost-in-the-middle 回避）
構造化: プロジェクト構造を明確に示す

Claude Code の強み

内部で自動的にコンテキストを最適化（詳細は Claude Code の実行モデル）
MCP によって必要な情報だけを効率的に取得
thinking block の削除と履歴圧縮で長期タスクも安定

ユーザー側で適切なコンテキスト管理を行うことで、Claude Code のポテンシャルを最大限に引き出せます。

📚 関連記事

Claude Code の実行モデル - Claude Code の内部実行モデル（thinking block、MCP、コンテキスト圧縮の詳細）