長いセッションで「会話履歴が要約されました」と出てきて、その後の応答が前の指示を覚えていないように見える。auto-compactは自動で動くぶん、何を残して何を捨てるかを把握していないと作業が壊れます。/compactと/clearの境目、focus引数、CLAUDE.mdでの制御まで、Claude Code v2系の現行仕様で整理しました。
auto-compactは何を要約して何を捨てるのか
Claude Codeの公式ドキュメントHow Claude Code worksには、コンテキスト管理について “When context fills up” セクションがあります。そこに書かれている動作はシンプルです。
Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved.
2段階で空きを作る
圧縮は1ステップではありません。先に古い tool output(Read結果やBash出力)を捨てます。それでも足りなければ会話そのものを要約。あなたが書いたプロンプトと重要なコード断片は残す設計。
つまり「結果は消えてもいいが、指示と判断は残る」という前提で動いています。問題はRead結果に重要な情報が埋まっているケース。設計書のテキストや外部ドキュメントの引用は、消えた後に困りもの。残したいならCLAUDE.mdか会話本文に転記しておく必要があります。
200kトークンのうちどこで走るか
Claude Codeのコンテキストウィンドウは200,000トークンです。auto-compactは上限ギリギリで動くわけではなく、Anthropic API側のデフォルト仕様では150,000トークン(下限50,000)で圧縮トリガーが引かれます。つまり残り50,000トークンぶんのバッファを持って前倒しで実行される、と覚えておくと挙動が読めます。
[使用量の目安]
0 ────────────────── 150k ──── 200k
↑ ↑ ↑
会話開始 compact hard limit
トリガー実行結果(イメージ):
$ /context
Context usage:
Tools: 18.2k tokens
System: 4.1k tokens
Messages:142.3k tokens
Total: 164.6k / 200k会話メッセージが14万トークンを超えた時点で、次のターンに入る前にauto-compactが動き出します。/contextで常時確認できます。
/compactと/clearの使い分け早見表
需要が一番多い疑問です。手短に並べます。
| コマンド | 会話履歴 | セッションID | checkpoint | 用途 |
|---|---|---|---|---|
/compact | 要約して残す | 同じ | 残る | 同じタスクを継続したい |
/compact <focus> | focusに沿って要約 | 同じ | 残る | 残したい論点を指定したい |
/clear | 全消去 | 新規 | 失われる | 別タスクに切り替えたい |
判断軸はひとつ。「次の作業に過去の文脈が要るか」。要るなら/compact、要らないなら/clear。中途半端に残すよりは/clearでリセットしたほうが、Claudeが古い前提を引きずるリスクは消えます。
/compactをfocus付きで実行する
コードから入ります。API仕様の修正タスクの途中で、依存ライブラリの調査ログだけが重くなっている状況。
/compact focus on the API changes we agreed on. Drop the dependency exploration logs.実行直後の表示:
Compacting conversation...
Original: 158,200 tokens
After compact: 12,400 tokens
Preserved: API schema decisions, current diff
Dropped: dependency search results, file tree dumpsfocus引数は単なるヒントではなく、要約プロンプトの一部として渡されます。日本語でも英語でもどちらでも通る挙動です。
focusに書くべき3つの軸
何を書くかで残るものが変わります。実用上効くのは「論点・成果物・除外」を明示すること。
- 論点: 何のタスクをやっているか(例: “OAuth2のリフレッシュトークン実装”)
- 成果物: 残してほしい具体物(例: “src/auth/refresh.tsの現行diff”)
- 除外: 捨てていい内容(例: “jwt関連ライブラリの比較メモは不要”)
focusなしと比べると何が変わるか
focusを書かない場合は公式のデフォルト要約プロンプトに置き換わる仕組みです。原文はAnthropic API側のCompactionドキュメントに載っているので、興味があれば“Custom summarization instructions”セクションを見ると一致が確認できます。デフォルトは汎用的にまとめるため、コードスニペットの優先度が下がりがち。実装中にfocusなしで圧縮すると、diff部分が要約に潰されるリスクが残ります。
CLAUDE.mdにCompact Instructionsを書く
公式ドキュメントから直接引用します。
To control what’s preserved during compaction, add a “Compact Instructions” section to CLAUDE.md or run
/compactwith a focus.
毎回/compactのあとに長いfocusを書くより、CLAUDE.mdに常駐の指示を入れておくほうが楽です。プロジェクトごとに残すべき情報が固定されている場合は、こちらが本筋。
# Compact Instructions
圧縮時は次の情報を必ず残してください。
- 現在編集中のファイルパスと未コミットdiff
- ユーザーから渡された仕様書の引用部分
- DBスキーマやテーブル定義
捨ててよいもの:
- Bashコマンドの出力(再実行可能)
- パッケージインストールログ
- ファイルツリー全体のdumpこのセクションがあると、auto-compactが走ったときに「diffは残し、コマンド出力は捨てる」がデフォルトになります。/compactを手動で叩く頻度は明確に減ります。
Claude Code memoryとは？CLAUDE.mdとの違いと運用設計の実例でCLAUDE.md自体の運用は書いたので、Compact Instructionsはそこへの追記として組み込むのが扱いやすいです。
「Autocompact is thrashing」エラーが出たら
稀に出る固有エラーです。公式の“Auto-compaction stops with a thrashing error”セクションに明文化されています。条件は圧縮後にすぐコンテキストが満杯になる状況が数回続いた場合。Claude Codeはループを避けるためにそこで止まります。
典型的な発火原因
巨大ファイルを丸ごとReadした、長いログをBashで吐かせた、画像をまとめて読み込んだ、のいずれか。要約しても次のターンで同じファイルが再ロードされるため、空きが瞬殺されます。
復旧手順
公式の推奨手順をそのまま並べます。
- 大きなファイルは line range や関数単位に分けてReadする
/compact keep only the plan and the diffのように、巨大出力を明示的に落とすfocusで再実行- 大きいファイルを扱う作業をsubagentに移し、メインのコンテキストを汚さない
- 過去の会話がもう不要なら
/clearで全捨て
サブエージェントで別コンテキストに逃がす
auto-compactで戦うより、最初から別コンテキストでやるほうが速いケースが多いです。
圧縮で戦うパターン
メイン会話で50MBのCSVをRead。中身を要約してもらう。その後別タスクへ移っても要約が残るぶん、後続のタスクで邪魔になります。
サブエージェントに逃がすパターン
サブエージェントを呼んでCSVを処理させ、結果だけ受け取る。サブエージェント側のコンテキストは独立しているため、終了後はメイン会話に何も残りません。
[main session: 18k tokens]
└─ Task(subagent: data-analyzer)
[subagent context: 0 → 80k → done]
returns: "top 5 outliers: id=42, 91, 103, 188, 244"
[main session: 18.2k tokens] ← 0.2kしか増えない並列実行のコスト感はClaude Codeのサブエージェント並列実行—コスト管理と設計のハマりどころにまとめています。圧縮で粘る前に、最初から分けたほうが安く済むケースがあります。
Anthropic API側のcompactionとの関係
Claude CodeはCLI側の実装ですが、根っこの仕組みはAnthropic APIの Compaction 機能と地続きです。自前でエージェントを組むときに同じ機能をMessages APIから使えます。
betaヘッダで有効化する
API側はベータ機能扱いです。anthropic-beta: compact-2026-01-12 ヘッダを付けて、context_management.editsにcompact_20260112を入れます。
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-4-7",
max_tokens=4096,
messages=[{"role": "user", "content": "Help me build a website"}],
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 150000},
}
]
},
)
print(response)レスポンス例:
BetaMessage(
id='msg_...',
content=[
BetaTextBlock(text='Sure, I can help...'),
],
usage=BetaUsage(input_tokens=12, output_tokens=148),
)パラメータの境界値
公式の “Trigger configuration” セクションには、triggerの値域が明記されています。
| パラメータ | デフォルト | 制約 |
|---|---|---|
trigger.value | 150,000 | 50,000以上 |
pause_after_compaction | false | 要約後に応答を一旦止める |
instructions | null | カスタム要約プロンプト(デフォルトを完全に置換) |
自前のエージェントで使う場合、pause_after_compaction=trueは強力です。要約が走った瞬間に応答が止まるため、要約内容をログに保存してからユーザーに見せる、といった介入ができます。Claude Code側にこのパラメータの直接の露出はありませんが、概念として知っておくとデバッグの解像度が上がります。
まとめ
Claude Codeのauto-compact運用で押さえたい点を並べておきます。
- auto-compactは tool output を先に捨て、足りなければ会話を要約する2段階方式
- トリガーは入力トークン約150kで、200kコンテキストに対し50kのバッファを持つ
- 同じタスクを継続するなら
/compact、別タスクへ移るなら/clear /compactはfocus引数で「論点・成果物・除外」を渡せる- CLAUDE.mdにCompact Instructionsセクションを書けば毎回指示せずに済む
- thrashingエラーは巨大ファイルの再ロードが原因。subagentに逃がすのが定石
- Anthropic API側の
compact_20260112と仕組みは共通。自前エージェントでも同じ調整が可能
圧縮で粘るより、最初からコンテキスト管理術で書いた構造で会話を始めるほうが結果的に楽なケースが多いです。auto-compactは保険として置き、CLAUDE.mdとsubagentで先回りする運用に落ち着きました。