context-engineering

コンテキストエンジニアリング

AI コーディングセッションにおけるコンテキストの流れは、4 つの操作ですべて制御できます。これらを使いこなせば、あらゆる応答の品質を自在に高められます。

4 つの操作

1. 書き出す — コンテキストの外部に情報を保存する

情報をコンテキストウィンドウの外に移し、圧縮やセッションの切り替え後も保持される永続ストレージに保存します。

保存先：

保存先	用途	例
CLAUDE.md	プロジェクトの恒久的なルール	「常に pnpm を使い、npm は使わない」
NOTES.md / scratchpad	現在のタスクの作業状態	アーキテクチャ上の決定事項、未解決の質問
.claude/memory/	学びとパターン	修正から得た [LEARN] ルール
外部ファイル	コンテキストに収まりきらないデータ	テスト計画、移行チェックリスト

パターン — スクラッチパッドのワークフロー：

1. Start complex task → create NOTES.md with goals and constraints
2. After research → write findings to NOTES.md
3. After compaction → NOTES.md survives, context does not
4. Resume → read NOTES.md to recover full state

2. 選択する — 関連情報を取得する

適切なタイミングで、適切な情報をコンテキストに取り込みます。量よりも精度が重要です。

精度の高い順に並べた方法：

1. @file 参照 — 指定したファイルを正確に取り込む
2. grep / Glob — 対象を絞ったパターン検索
3. サブエージェントによる探索 — 詳細な検索を委任
4. RAG / embeddings — 大規模なコードベースからのセマンティック検索

重要な原則：絞り込んだ 300 トークンのほうが、焦点の定まらない 113K トークンより有用です。

関数シグネチャを正確に返すピンポイントな grep の結果は、モジュール全体をコンテキストに流し込むよりも有用です。無関係なトークンが増えるほど、注意が分散します。

パターン — 段階的な情報取得：

1. Start with file names (Glob)
2. Narrow to specific functions (Grep)
3. Read only the relevant lines (Read with offset+limit)
4. Never read entire large files when you need one function

3. 圧縮する — 重要な情報を保ちながらトークンを減らす

重要な情報を失わずに、コンテキストを小さくします。

圧縮戦略：

戦略	方法	タイミング
焦点を指定した /compact	/compact focus: auth module changes	タスクの区切り
マイクロ圧縮	Claude にツールの出力をその場で要約させる	大量の読み取りや検索の後
先頭＋末尾	大きな出力の最初の 20 行と最後の 20 行を読む	ログ分析、テスト結果の確認
ツール結果のクリア	サブエージェントの結果を報告後に自動でクリアする	大規模な探索
セマンティック選択	調査結果を要約し、生データを破棄する	調査フェーズ

圧縮のタイミング：

• 計画を立てた後、実装に着手する前
• 機能やマイルストーンを完了した後
• コンテキストが 50% を超えたとき（CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 を設定）
• タスクの領域を切り替える前
• 大規模な検索や読み取りを行った後

PostCompact フック — 重要なコンテキストを再注入する：

{
  "type": "PostCompact",
  "command": "cat .claude/critical-context.md"
}

これを使うと、プロジェクトのルール、現在のタスクの状態、アーキテクチャ上の制約を、圧縮のたびに確実に保持できます。

4. 分離する — 実行環境を分割する

すべてを 1 つのコンテキストに読み込まないでください。作業を独立した実行環境に分割します。

方法	分離レベル	使用する場面
サブエージェント	分岐したコンテキスト	大規模な探索、テストの実行、ドキュメントの生成
Worktree（claude -w）	リポジトリ全体のコピー	機能の並行開発、複数のアプローチの比較
/btw（Claude Code 組み込み機能）	一時的なオーバーレイ	会話履歴に含めずに簡単な質問をする
エージェントチーム	独立したセッション	レイヤーをまたぐ変更、並行レビュー
新しいセッション（/resume）	クリーンな状態	無関係な作業、コンテキストの劣化

パターン — サブエージェントへの委任：

Main session: planning, coordination, commits
Subagent 1: explore auth module, report findings
Subagent 2: run test suite, report failures
Subagent 3: generate migration script

メインのコンテキストは整理された状態に保たれます。大量の作業はサブエージェントが担当します。

コンテキスト予算の計画

基準の例（/context で調整してください）：200K のコンテキストウィンドウ（Haiku 4.5。Fable 5.1、Opus 5.5、Sonnet 5 は 1M）では、オーバーヘッドが約 20K（CLAUDE.md、ツール定義、MCP スキーマ）のため、使用可能なのは約 180K です。コンテキストが埋まるにつれて品質は低下するため、1M のモデルでも同じ方針を守ってください。実際の予算はモデルや構成によって異なります。

割り当て	予算	内容
静的コンテキスト	20-30K	CLAUDE.md、ツールスキーマ、MCP 定義
動的コンテキスト	150-180K	コード、会話、ツールの結果

静的コンテキストを先に配置します。 CLAUDE.md とツール定義は会話より先に読み込まれます。これらを安定させることでプロンプトキャッシュのヒット率が最大化され、コストとレイテンシーを抑えられます。

フェーズ	使用量の目標	超過した場合の対応
計画	< 20%	計画を簡潔にし、スクラッチパッドに書き込みます
実装	< 50%	ファイル間でコンパクションし、読み取りを委任します
テスト	< 70%	テストの実行をサブエージェントに委任します
レビュー	< 85%	品質が低下したら新しいセッションを開始します

/clear、/compact、サブエージェントの使い分け

状況	対応
タスクの区切りで、学びを保持したい	要点を指定して /compact
コンテキストの品質が低下し、Claude が同じことを繰り返している	/compact。それでも改善しない場合は /resume
関連のない作業を始める	/clear または新しいセッション
大量の読み取り／検索を行う	サブエージェントに委任
簡単な寄り道の質問	/btw（メインコンテキストを汚しません）
複数のアプローチを検討する	ワークツリーまたはエージェントチーム

アンチパターン

• 1 つの関数だけ必要なのにファイル全体を読み込む
• 必要な情報を抽出した後も、MCP ツールの結果をコンテキストに残す
• 15 個以上の MCP を実行する（リクエストごとにツールスキーマのオーバーヘッドが増えます）
• Claude に広範囲な検索を強いる曖昧なプロンプト（「コードを修正して」など）
• 自動コンパクションが 95% で起動するまでコンパクションしない

CLAUDE.md に追加

## Context Engineering

Write to NOTES.md for working state that must survive compaction.
Select with precision — grep first, read specific lines, never dump whole files.
Compact at 50% or task boundaries. Set CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50.
Isolate heavy work to subagents. Main session stays for coordination and commits.