第2章 コンテキスト管理

はじめに

モデルが一度に扱える情報量（コンテキストウィンドウ）には上限があります。
ハーネスの重要な仕事のひとつが、この限られた領域に「何を・どの順番で・いつまで」入れるかを管理すること です。

本章では、Claude Code がコンテキストをどう組み立て、長いセッションでどう維持するかを解説します。

---

2.1 コンテキストに入るもの

Claude Code がモデルに送るリクエストは、おおよそ次の要素で構成されます。

flowchart TD
    subgraph Context["コンテキストウィンドウ"]
        direction TB
        A["システムプロンプト<br/>（ハーネスが生成：ツール定義・環境情報・行動指針）"]
        B["CLAUDE.md<br/>（プロジェクト固有の指示・規約）"]
        C["会話履歴<br/>（ユーザー発言・モデル応答・ツール実行結果）"]
        D["直近のユーザー入力"]
    end
    A --> B --> C --> D

1. システムプロンプト — ハーネスが自動生成します。
   利用可能なツールの定義、作業ディレクトリ、OS、git の状態などの環境情報が含まれます。
   ユーザーが直接編集することはできませんが、--append-system-prompt オプションや設定で追記できます。
2. CLAUDE.md — プロジェクトの「取扱説明書」としてユーザーが管理するファイル。
   後述します。
3. 会話履歴 — ツールの実行結果（ファイル内容・コマンド出力）もここに蓄積されるため、セッションが長引くほど消費量が増えます。

---

2.2 CLAUDE.md — プロジェクト知識の注入

CLAUDE.md は、セッション開始時にハーネスが自動でコンテキストに読み込むメモリファイルです。
複数の場所に置くことができ、すべてがマージされます。

配置場所	スコープ	用途例
~/.claude/CLAUDE.md	ユーザー全体（全プロジェクト）	個人の好み（言語、コーディングスタイル）
<repo>/CLAUDE.md	プロジェクト（チーム共有）	ビルドコマンド、アーキテクチャ、規約
<repo>/CLAUDE.local.md	プロジェクト（個人・git管理外）	ローカル環境固有の情報
<subdir>/CLAUDE.md	サブディレクトリ	モノレポの各パッケージ固有の指示

記述例：

# プロジェクト概要
このリポジトリは Astro + Starlight のドキュメントサイトです。

## コマンド
- 開発サーバー: pnpm dev
- ビルド: pnpm build
- Lint: pnpm biome check

## 規約
- ドキュメントは日本語で書く
- コミットメッセージは Conventional Commits に従う

CLAUDE.md 運用のコツ

CLAUDE.md は毎回コンテキストを消費します。「Claude が毎回知っている必要があること」だけ を簡潔に書き、詳細は必要時に読ませるファイルへのポインタ（パス）に留めるのが効率的です。/init コマンドを使うと、リポジトリを解析して初期版を自動生成できます。

また、@path/to/file 形式で他のファイルをインポートする記法もサポートされており、共通規約を分割管理できます。

---

2.3 自動コンパクション（要約による圧縮）

セッションが長くなりコンテキストウィンドウの上限に近づくと、ハーネスは 自動コンパクション を実行します。

flowchart LR
    A["会話履歴が<br/>上限に接近"] --> B["ハーネスが履歴を<br/>要約（サマリー化）"]
    B --> C["要約 + 直近の履歴で<br/>コンテキストを再構成"]
    C --> D["作業を継続"]

• 古い会話は要約に置き換えられ、タスクの目的・決定事項・進行状況 が引き継がれます
• /compact コマンドで手動実行もできます（/compact 要約時はテスト結果を重視して のように指示も付けられます）
• 要約で失われては困る情報（重要な決定・制約）は、CLAUDE.md やファイルに書き出しておくと安全です

注意

コンパクションは便利ですが、細部（特定のエラーメッセージの全文など）は失われることがあります。
長時間のデバッグセッションでは、重要なログをファイルに保存させる運用がおすすめです。

---

2.4 コンテキストを節約するハーネスの工夫

ハーネスは、コンテキストを無駄遣いしないための仕組みを複数持っています。

• ツール結果の切り詰め — 巨大なコマンド出力やファイルは、一定サイズで切り詰められます
• 部分読み込み — Read ツールは offset / limit でファイルの一部だけを読めます
• サブエージェントへの委譲 — 大量のファイル探索は、独立コンテキストを持つサブエージェント（第7章）に任せ、結論だけを受け取ることで親のコンテキストを守ります
• プロンプトキャッシュ — 変化しない先頭部分（システムプロンプト・CLAUDE.md）は API 側でキャッシュされ、コストとレイテンシを削減します

---

2.5 セッションの継続と再開

コンテキストはセッション単位で保持されますが、ハーネスは過去セッションの記録をローカルに保存しています。

コマンド	動作
claude --continue	直近のセッションを引き継いで再開
claude --resume	過去のセッション一覧から選択して再開
/clear	現在のコンテキストを破棄して新規開始

ヒント

タスクの区切りごとに /clear する習慣をつけると、無関係な履歴によるコンテキスト圧迫と挙動のブレを防げます。

---

まとめ

• コンテキストは「システムプロンプト + CLAUDE.md + 会話履歴」で構成され、ハーネスが組み立てる
• CLAUDE.md は配置場所ごとにスコープが異なり、簡潔に保つことが重要
• 上限に近づくと自動コンパクションが走り、要約で作業が継続される
• 大きな探索はサブエージェントに委譲するなど、ハーネスはコンテキスト節約の仕組みを備えている