Claude Code compactとauto-compactの発火条件、要約後に残る情報

Claude Codeのcompactは、会話が長くなってコンテキストウィンドウが埋まってきたときに、会話履歴を要約して空き容量を作る処理です。自動でも手動(/compact)でも仕組みは同じで、発火するタイミングと要約リクエストの扱われ方が違うだけです。本稿では、自動発火の条件、要約後に何が残り何が消えるか、コストがどう動くか、そしてフックで介入する方法までを扱います。modから圧縮を見送る方法はsession.compactの解説にあります。

先に結論を挙げます。

• 発火のタイミング: 1Mウィンドウを持つ構成(API直結のSonnet 5・Haiku 5.5・Fable系・Opus 4.7以降)では約967Kトークンで先回りして走ります。200Kウィンドウで動く構成では200Kトークン境界が目安です。早めたいときは/autocompactでウィンドウを小さくするか、CLAUDE_AUTOCOMPACT_PCT_OVERRIDEで発火率を下げます。この環境変数は既定より上げる方向には効きません
• 要約で優先する内容の指定: /compactの後ろに指示を書くか、CLAUDE.mdにCompact instructionsの節を置きます。書き方は後段の/compactの節にあります
• Autocompact is thrashing: 要約した直後にファイルやツール出力がまた上限まで埋めてしまう状態が続いたときの停止です。復旧の手順はエラーの節にあります

コンテキストが埋まるとClaude Codeはまず何をするか

上限に近づいたとき、Claude Codeはいきなり要約から始めるわけではありません。まず古いツール出力をクリアし、それでも足りなければ会話全体を要約します。直近のリクエストと重要なコードスニペットは残りますが、会話の早い段階にあった細かい指示は失われることがあります。Messages APIを直接使う実装では、要約プロンプト自体をinstructionsパラメータで差し替えて残したい情報を指定できます。

auto-compactは、この自動処理を指す機能名です。手動の/compactと処理内容は同じで、コンテキストウィンドウが満杯になる前に自動側が同じ処理を肩代わりします。コンテキストウィンドウが満杯になった瞬間にセッションが終わるわけではなく、この自動処理がその手前で割り込みます。

起動場所や読み込み除外設定でコンテキストに入れる情報量を事前に絞る設計は、Claude Codeのコンテキスト管理で扱いました。ここから先は、埋まった後に何が起きるかです。

auto-compactはいつ発火するか — モデルと接続経路で変わるしきい値

auto-compactの発火しきい値は、単一のパーセンテージでは説明できません。モデルと接続経路によって、先回りで走る4パターンと、上限到達後に走る既定の動きに分かれます。

ゲートウェイ経由の扱いは、モデルIDを認識できるかで分かれます。ANTHROPIC_BASE_URLをLLMゲートウェイに向けても、認識できるモデルにはAnthropic APIと同じウィンドウが割り当てられます。Sonnet 5以降やOpus 4.7以降なら1Mのままです。ただしゲートウェイやその先のサーバーが課す上限は検出できません。200Kを超えるリクエストをゲートウェイが拒否するなら、/autocompact 200kで200K境界に合わせます。

しきい値はCLAUDE_CODE_AUTO_COMPACT_WINDOWで変更でき、1Mモデルであえて500000のように小さい値を指定すれば、その値を基準にcompactが早まります。値はモデルの実際のコンテキストウィンドウで頭打ちになり、設定するとステータスラインのused_percentage(常にモデル全体のウィンドウ基準)とcompactのしきい値が一致しなくなります。変更手段は環境変数のほかにもあるので、後段の節で優先順位と実機の出力をあわせて扱います。

もう一段細かく発火タイミングを早めたい場合はCLAUDE_AUTOCOMPACT_PCT_OVERRIDEが使えます。発火パーセンテージを下げて、compactを早めに走らせる設定です。この変数が効くのは、モデルの上限より手前で先回りしてcompactする構成に限られます。

対象は上の表の先回り型の行です。API直結のSonnet 5・Fable系・Opus 4.7以降や、200K境界のモデルが当たります。CLAUDE_CODE_AUTO_COMPACT_WINDOWを設定した場合も効きます。クラウドセッションはこの変数を自前で設定しており、環境変数に追加しても発火タイミングは変わりません。

既定より高い値を指定しても効果はありません。下げる方向にしか働かないためです。メイン会話とサブエージェントの両方に適用されます。

CLAUDE_CODE_MAX_CONTEXT_TOKENSは「コンテキストウィンドウを拡張する設定」ではありません。Claude Codeが認識済みのClaudeモデルに対しては、DISABLE_COMPACTと併用しない限り効果を持ちません。主な用途は、ゲートウェイ経由で接続する認識されないモデルIDや独自エイリアス向けの上書き設定です。ゲートウェイ側の実際のウィンドウサイズが、モデル名から想定される値と食い違う場合に使います。

compact後に残る情報、消える情報

compactが生成されると、会話履歴は短い構造化された要約に置き換わります。要約に入るのは、依頼とその意図、重要な技術概念、調べた・変更したファイルと主要なコード、エラーとその直し方、保留中のタスク、いま進めている作業です。ツールの出力全文や途中の推論は残りません。直近に読んだか変更したファイルは、最大5件をClaude Codeが読み直します。5,000トークンを超えるファイルは、中身ではなくReferenced fileというパス参照だけで戻ります。呼び出し済みのSkillは再注入されます。ファイルの中身そのものは要約には入らず、Claudeは作業の経緯を参照できても、正確な内容は持たなくなります。ただし、コンテキストに載る情報のすべてが会話履歴を経由しているわけではありません。システムプロンプトのようにそもそもメッセージ履歴に含まれないものもあれば、CLAUDE.mdのようにディスクから読み直されるものもあり、仕組みによって復元のされ方が変わります。

なお、要約を生成するリクエスト自体も、セッションで拡張思考が有効なら思考ありで実行されます。この表は、大規模コードベースでCLAUDE.mdを階層化したときにcompactでどこが消えるかにも直結します。

パス指定ルールとネストしたCLAUDE.mdは、トリガーとなるファイルが読まれた時点でメッセージ履歴に載る仕組みです。そのため、compactは他のすべてと一緒にそれも要約へ畳んでしまいます。再びロードされるのは、次にマッチするファイルを読んだときです。compactを越えて常に効かせたいルールがあるなら、paths:フロントマターを外すか、プロジェクトルートのCLAUDE.mdへ移します。プロジェクトルートのCLAUDE.mdやスコープなしのルールなら、compact後にディスクから再注入されます。

Skillについても再注入の対象は「実際に呼び出した本文」だけです。起動時にロードされるSkillの説明一覧(まだ呼び出していないものを含む)はcompact後に再ロードされません。大きなSkillは冒頭から切り詰められて上限に収まるため、SKILL.mdの重要な指示は冒頭付近に置いておくほうが、切り詰められずに残りやすくなります。

1Mトークンウィンドウ対応モデル(Fable 5.1、Fable 5、Sonnet 5.5、Sonnet 5、Opus 4.6以降、Sonnet 4.6)でも、動き方は変わりません。上限が大きくなるだけで、要約の仕組みは同じです。

/compactと/clear、/rewind、要約からの再開はどう使い分けるか

コンテキストを操作する手段は/compactだけではありません。目的が違う4つの選択肢を並べると使い分けが見えます。

/rewind(または入力欄が空の状態でのEsc二連打)を開くと、送ったプロンプトごとの巻き戻し地点が並んだメニューが出ます。既定の「Restore code and conversation」はコードと会話を両方戻す操作で、コンテキストだけ整理したい場合は「Restore conversation」を選べばファイルは現状のまま会話だけ戻ります。逆に会話は残してコードだけ戻したいときは「Restore code」です。同じメニューにある「Summarize from here」「Summarize up to here」は選んだ範囲だけを/compactと同様に要約する操作で、ファイルには一切手を付けません。

/compactは要約を生成するためにAPIリクエストを送りますが、/clearは会話を空にするだけでリクエストを伴わないため、操作自体に費用はかかりません。同じタスクを続けていても会話が長くなるほど参照精度は落ちるため、要約で粘るか/clearに踏み切るかの目安はClaudeの長い会話は精度が落ちる — context rotの根拠と/clearの目安で扱っています。

/compactには要約時に何を優先するかの指示を渡せます。

/compact Focus on code samples and API usage

指示を毎回打つのが面倒なら、CLAUDE.mdに固定の方針を書いておく方法もあります。

# Compact instructions
 
When you are using compact, please focus on test output and code changes

会話のターンが少なすぎて要約できないときは、Not enough messages to compact.と返ります。1回の大きな貼り付けでコンテキストが埋まった場合でも出るため、そのときは/clearで始め直します。

要約からの再開ダイアログは、Pro/Maxプランの機能です。セッションが約1時間以上放置され、かつ10万トークンを超えていると、最初のメッセージを送る前に表示されます。この時点でキャッシュはすでに切れているため、次のリクエストはどちらを選んでも一度だけフル履歴を処理します。

compactはコストをどう変えるか — プロンプトキャッシュとの関係

compactは会話履歴を要約に置き換えるため、設計上、会話レイヤーのキャッシュは必ず無効化されます。次のリクエストは短くなった新しい履歴を運び、古い履歴とプレフィックスを共有しないためです。一方でシステムプロンプトのレイヤーは使い回され、CLAUDE.mdとメモリーがセッション開始時から変わっていなければディスクからの再読み込みもキャッシュヒットします。

要約そのものを生成するリクエストは、会話と同じシステムプロンプト・ツール・履歴に要約指示を追加した別リクエストとして送られます。キャッシュが温かいうちに打てば、このリクエストはプレフィックスをキャッシュから読むため、見かけのコンテキストサイズから想像するより安く済み、時間の大半は要約の生成そのものに費やされます。

話が変わるのは、キャッシュの有効期間を過ぎてから放置した場合です。有効期間はサブスクリプションでは1時間です。APIキーやAmazon Bedrock、Google CloudのAgent Platform、Microsoft Foundry、Claude Platform on AWSでは既定5分ですが、ENABLE_PROMPT_CACHING_1H=1で1時間に延長できます。ただし、プラン上限を超えてusage creditsを使っている間は、1時間TTLのキャッシュ書き込みが高くつくため自動的に5分TTLへ落ちます。

この期間を超えて放置した後にcompactすると、読めるキャッシュが残っていません。そのため要約リクエストは全履歴を非キャッシュで再処理します。これが「古いセッションを再開した直後の/compactが一番高くつく」理由です。

タスクの区切りのようなキリのいいタイミングで/compactを打てば、auto-compactがタスクの途中で割り込むのを待たずに済みます。ある方向性を丸ごと捨てたいだけなら、/rewindのほうが合っています。すでにキャッシュ済みのプレフィックスまで戻るだけなので、compactのように新しいプレフィックスを組み立て直す必要がありません。プロンプトキャッシュの基礎はPrompt Cachingを理解するを参照してください。

PreCompactとPostCompactフックでcompactに介入する

compactの前後にはフックで介入できます。

PreCompactはcompact操作が実行される直前に走ります。matcherの値でトリガーの種類が分かります。manualが/compact、autoが会話がauto-compactのウィンドウに達したときの自動compactです。終了コード2を返すか{"decision": "block"}を含むJSONを返すと、compactをブロックできます。手動の/compactをブロックした場合、標準エラー出力のメッセージがユーザーに表示されます。

自動compactをブロックしたときの挙動は、発火タイミングで2通りに分かれます。上限に達する前に先回りで走ろうとしたcompactをブロックした場合は、そのままスキップされ、会話は圧縮されずに続く形です。一方、すでにAPIから返っていたコンテキスト上限エラーから回復するために走ろうとしたcompactをブロックした場合は、元のエラーがそのまま表面化し、リクエストは失敗します。

PreCompactの入力には共通フィールドに加えてtriggerとcustom_instructionsが渡されます。manualの場合、custom_instructionsにはユーザーが/compactに渡した文字列が入ります。何も渡さなければnullです。autoの場合もnullです。

PostCompactはcompact完了後に走り、triggerと、生成された要約が入ったcompact_summaryを受け取ります。生成された要約をログに残したり、外部の状態を更新したりする用途に向いています。PostCompactには決定を左右する力はなく、結果には影響しません。

matcherにcompactを指定したSessionStartフックを組み合わせると、compactのたびに任意のコマンド出力をコンテキストへ再注入できます。標準出力に書いた内容がそのままClaudeのコンテキストに追加される仕組みです。フックの入出力仕様はClaude Code Hooks完全ガイドにまとめています。

コンテキストを溢れさせないための運用

/contextコマンドを使うと、現在のコンテキスト使用量を色分けされたグリッドで確認できます。コンテキストを多く使っているツールやメモリーの肥大も、改善案つきで指摘されます。会話がウィンドウの上限を超えている場合は、出力の先頭に警告が出ます。どれだけ超過しているか、どのコマンドで空きを作れるかが分かります。フルスクリーンモードで実行すると、グリッドを見せるために項目ごとの内訳が畳まれます。allを渡すと展開されます。

ステータスラインでも、context_window.used_percentageのようなフィールドで使用率を常時表示できます。スクリプトは/compactの完了時にも再実行される仕組みです。ただしcontext_windowの値は直近のAPI応答由来で、current_usageはcompact直後から次のAPI呼び出しまでnullになります。減った使用量が反映されるのは次のリクエスト以降です。

コンテキストを圧迫しやすいのは、大きなファイルの丸読みやツール出力です。サブエージェントに作業を委譲すれば、その作業は独立したコンテキストウィンドウの中で進み、メインの会話は消費を抑えられます。拡張思考の設定はセッションから引き継がれるため、委譲先でも同じ思考深度で処理される点は変わりません。サブエージェントの設計判断はClaude Code Sub-agents完全ガイドにまとめてあります。

コンテキストが埋まりやすいプロジェクトでは、Compact instructionsをあらかじめ書いておく価値があります。

compactで起きるエラーと復旧の手順

compactに関わるエラーは2種類あります。

スラッシングエラーは、自動compactが成功したにもかかわらず、直後にファイルやツール出力がコンテキストを再び埋めてしまう状態が連続したときに出ます。Autocompact is thrashing: the context refilled to the limit...というメッセージとともに、Claude Codeは進捗の出ないループでAPI呼び出しを浪費しないよう、リトライを止めます。この検知が入る前は圧縮が延々と繰り返され、コンテキスト残量表示が0%近くに張り付いたまま動かなくなる不具合も報告されていました。復旧の選択肢は次の4つです。

Prompt is too longは、会話と添付ファイルの合計がモデルのコンテキストウィンドウを超えたときに出ます。auto-compactは既定で有効で、通常はこのエラーを防ぐ仕組みです。auto-compact自体が失敗した場合は、次の形で表示されます(v2.1.229以降)。Prompt is too long · automatic compaction failed: <原因のエラー>です。DISABLE_AUTO_COMPACTを設定している場合は、再度有効にするか、ウィンドウが埋まる前に手動で/compactを実行する必要があります。復旧策には、使っていないMCPサーバーを/mcp disable <name>で無効化し、そのツール定義をコンテキストから外す方法も含まれます。MCPツール定義は既定で必要になるまで読み込まれず、常駐するのはツール名とサーバーの指示だけです。それでも不要なサーバーを無効化しておけば、その分の消費を減らせます。

/contextの超過警告(v2.1.216以降)は出力の先頭に出ます。文言は2パターンあり、挙動そのものも異なります。モデル自体の実際の上限を超えている場合は、空きを作るまでリクエストがPrompt is too longで失敗し続け、run /compact or /clear to continueと表示されます。

一方、compactのしきい値がモデル上限より小さく、そのしきい値だけを超えた場合は、モデル自体の上限にはまだ達していません。リクエストは失敗せずそのまま成功し、表示はrun /compact to reduce usageという警告に留まります(例: 1Mモデル上の200K境界)。DISABLE_COMPACTを設定している場合は、どちらの文言でも/compactの代わりに/clearが表示されます。

なお、モデルのフォールバックチェーンはcompactの場面もカバーしますが、Claude Codeはプライマリのモデルより小さいコンテキストウィンドウを持つモデルへはフォールバックしません。要約先で会話の一部が切れてしまうためです。フォールバック候補がすべて小さい場合は元のエラーがそのまま表示され、リトライが必要になります。

環境変数でしきい値を変える運用は、どこまで報われるか

CLAUDE_AUTOCOMPACT_PCT_OVERRIDEやCLAUDE_CODE_AUTO_COMPACT_WINDOWは、compactを早めに走らせるための正規の手段です。ただしこれらは発火の「タイミング」を動かすだけで、コンテキストを圧迫している「原因」そのものは変えません。巨大なツール出力が繰り返しコンテキストを埋めているなら、しきい値を下げてcompactを早めても、埋まり直す速度が変わらなければ同じ場所で何度もcompactが走るだけです。原因が特定のツール出力にあるなら、/compactのフォーカス指定やCLAUDE.mdのCompact instructions、サブエージェントへの委譲で入口を絞るほうが効きます。

しきい値をいじる操作には、もう一つ見落としやすい副作用があります。CLAUDE_CODE_MAX_OUTPUT_TOKENSで出力トークンの上限を引き上げると、auto-compactが発火する前の実効コンテキストウィンドウはむしろ縮みます。出力に割く分だけ、要約が走るまでに使える入力側の余地が狭くなるためです。

しきい値を変える4つの手段と、効く順番

ウィンドウの大きさ(どれだけ埋まったらcompactするか)を変える手段は、環境変数だけではありません。次の4つがあり、同時に指定したときは上にあるものが勝ちます。

/autocompactは、セッション中に打つとウィンドウを変えて、同じ値をユーザー設定へ保存するコマンドです。/autocompact autoで既定へ戻せます。マネージド設定のような上位のスコープがこのキーを握っていると、コマンドは値を保存するだけで、そのセッションの実効値は上位スコープのものが使われます。フラグはその制約を受けません。環境変数は数値の素の整数だけを受け付け、500kと書くと500として読まれて下限の100Kに丸められる点が、コマンドやフラグと違います。

フラグの値の検証は、モデルを呼ばずに手元で確かめられます。v2.1.286で、下限未満と数値以外を渡した結果は次のとおりです。

claude --autocompact 10k --version

error: option '--autocompact <auto|tokens>' argument '10k' is invalid. It must be 'auto', or between 100k and 1M (e.g. 500k, 200000, or 200 as shorthand)

abcのような数値でない文字列も同じ文言で弾かれます。受け付けるのはauto、または100kから1Mまでの値です。200のような100〜1000の裸の数字は千単位として読まれ、200は20万トークンを意味します。claude --helpの表示は次のとおりです。--autocompact <auto|tokens>が「Auto-compact window size (auto, or 100k–1M tokens)」と出ます。

/configに出てくるのは、自動compactのON/OFFにあたるautoCompactEnabledです。DISABLE_AUTO_COMPACT環境変数を設定していると、こちらの設定より環境変数が優先されます。

よくある質問

サブエージェントのコンテキストもcompactされますか

されます。サブエージェントは独立したコンテキストウィンドウを持つため、メインとは別のタイミングでcompactが走ります。プロンプトキャッシュの1時間TTLは既定ではメイン会話にしか適用されず、サブエージェントはサブスクリプションでも5分TTLです。subagentPromptCacheTtl(v2.1.242以降)で1時間に変更できます。

VS Code拡張でもcompactの見え方は同じですか

CLIとほぼ同じ仕組みですが、VS Code拡張ではcompactした会話を折りたたみ可能な「Compacted chat」カードとして表示する機能が追加されています。中身に要約が入る点は同じで、表示のされ方が利用しているツールごとに異なります。

まとめ

しきい値の環境変数をいじる前に、/contextで何がウィンドウを埋めているかを見るのが先です。原因が大きなツール出力なら/compactのフォーカス指定かサブエージェントへの委譲で、ゲートウェイの上限が原因なら/autocompactで境界を合わせます。導入やモデル選び、権限設計まで含めたClaude Codeの全体像はClaude Code(クロードコード)とはにまとめてあります。