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

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

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

上限に近づいたとき、Claude Codeはいきなり要約から始めるわけではありません。まず古いツール出力をクリアし、それでも足りなければ会話全体を要約します。直近のリクエストと重要なコードスニペットは残りますが、会話の早い段階にあった細かい指示は失われることがあります。

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

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

auto-compactはいつ発火するか — モデルと接続経路で分かれる4パターン

auto-compactの発火しきい値は、単一のパーセンテージでは説明できません。モデルと接続経路によって、次の4パターンに分かれます。

Sonnet 5はAPI上つねに1Mウィンドウで動作し、200Kバリアントや[1m]サフィックスの選択は存在しません。ただしANTHROPIC_BASE_URLがLLMゲートウェイを指していると、Claude Codeは1M対応を検証できないため200Kに切り詰めます。モデルピッカーで「Sonnet 5(1M context)」を選ぶとsonnet[1m]にマップされ、ゲートウェイ経由でも1Mウィンドウを使えます。この扱いはSonnet 5固有のもので、他モデルの一般的なゲートウェイ接続がすべて200K境界で先回り発火になるわけではありません。

しきい値はCLAUDE_CODE_AUTO_COMPACT_WINDOWで変更でき、1Mモデルであえて500000のように小さい値を指定すれば、その値を基準にcompactが早まります。値はモデルの実際のコンテキストウィンドウで頭打ちになり、設定するとステータスラインのused_percentage(常にモデル全体のウィンドウ基準)とcompactのしきい値が一致しなくなります。

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

• CLAUDE_CODE_AUTO_COMPACT_WINDOWを設定している場合
• クラウドセッション
• 拡張コンテキストなしのSonnet 4.6やOpus 4.6
• Anthropic API直結のSonnet 5(既定の約967Kのしきい値を基準にする)

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

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

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

compactが生成されると、会話履歴は短い要約に置き換わります。ただし、コンテキストに載る情報のすべてが会話履歴を経由しているわけではありません。システムプロンプトのようにそもそもメッセージ履歴に含まれないものもあれば、CLAUDE.mdのようにディスクから読み直されるものもあり、仕組みによって復元のされ方が変わります。

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

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

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

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

/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は会話を空にするだけでリクエストを伴わないため、操作自体に費用はかかりません。

/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

新しいセッションで会話履歴がまだ無い状態で/compactを打つと、Not enough messages to compact.と表示されるだけで何も起きません。

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

• 要約から再開: すぐに/compactが走り、以降のリクエストは要約だけを運びます
• フルセッションをそのまま再開: 全履歴が復元され、キャッシュが温かい間は以降のリクエストもキャッシュから読まれます
• 二度と確認しない: 以後は常にフルセッションが再開され、ダイアログ自体が二度と出なくなります

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です。終了コード2を返すか{"decision": "block"}を含むJSONを返すと、compactをブロックできます。手動の/compactをブロックした場合、標準エラー出力のメッセージがユーザーに表示されます。

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

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

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に関わるエラーは主に3種類あります。

スラッシングエラーは、自動compactが成功したにもかかわらず、直後にファイルやツール出力がコンテキストを再び埋めてしまう状態が連続したときに出ます。Autocompact is thrashing: the context refilled to the limit...というメッセージとともに、Claude Codeは進捗の出ないループでAPI呼び出しを浪費しないよう、リトライを止めます。復旧の選択肢は次の4つです。

• 巨大なファイルを小さなチャンクに分けて読ませる
• 大きな出力を除外するフォーカス付きで/compactを実行する(例: /compact keep only the plan and the diff)
• 大きなファイルを扱う作業をサブエージェントに移し、別のコンテキストウィンドウで処理する
• それ以前の会話が不要なら/clearを実行する

Prompt is too longは、会話と添付ファイルの合計がモデルのコンテキストウィンドウを超えたときに出ます。auto-compactは既定で有効で、通常はこのエラーを防ぐ仕組みです。DISABLE_AUTO_COMPACTを設定している場合は、再度有効にするか、ウィンドウが埋まる前に手動で/compactを実行する必要があります。復旧策には、使っていないMCPサーバーを/mcp disable <name>で無効化し、そのツール定義をコンテキストから外す方法も含まれます。サブエージェントは親セッションのMCPツール定義をすべて引き継ぐため、起動前に不要なMCPサーバーを無効化しておくと、最初のターンからコンテキストを圧迫するのを防げます。

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

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

Error during compaction: Conversation too longは、/compact自体が失敗したケースです。生成しようとした要約を収める空きコンテキストが足りないと起きます。auto-compactが発火した時点ですでにウィンドウが満杯だった場合や、Prompt is too longを見た後に/compactを実行した場合に起きやすくなります。復旧の手順は、Escを2回押してメッセージリストを開き、数ターン前まで戻ってから再試行することです。それでも空きが足りなければ、/clearで新しいセッションを始めます(以前の会話は保持され、/resumeで開き直せます)。

なお、モデルのフォールバックチェーンは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が発火する前の実効コンテキストウィンドウはむしろ縮みます。出力に割く分だけ、要約が走るまでに使える入力側の余地が狭くなるためです。

割合の調整は環境変数のみで行う設計で、/configに露出しているのはAuto-compactのON/OFF(autoCompactEnabled)だけです。細かいしきい値を変えたい場合は、CLAUDE_CODE_AUTO_COMPACT_WINDOWやCLAUDE_AUTOCOMPACT_PCT_OVERRIDEを環境変数として設定する以外の手段はありません。

よくある質問

/compactが意味のないタイミングで繰り返し走るのはなぜですか

多くの場合はスラッシングです。compact直後に大きなファイルやツール出力がコンテキストを再び埋めてしまうと、Claude Codeは3回連続の再充填を検出した時点でリトライを止めます。原因になっている出力を小さく分割するか、フォーカス付きの/compact、サブエージェントへの委譲のいずれかで入口を絞ります。

auto-compactを無効化できますか

DISABLE_AUTO_COMPACT=1で自動発火だけを止め、手動の/compactは残せます。autoCompactEnabled設定をfalseにする方法も同じ効果です。自動・手動の両方を止めたい場合はDISABLE_COMPACT=1ですが、コンテキストが埋まったときの逃げ道自体が無くなる点に注意が必要です。

compact直後にコストが跳ね上がることがあるのはなぜですか

プロンプトキャッシュの有効期間は、サブスクリプションで1時間、APIキーや各クラウドでは既定5分です。この期間を過ぎてから/compactを実行すると、要約を生成するリクエストがキャッシュを読めず、会話全体を非キャッシュで再処理します。キャッシュが温かいうちに実行すれば、同じ処理でも費用は大きく下がります。

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

されます。CLAUDE_AUTOCOMPACT_PCT_OVERRIDEは、メインの会話とサブエージェントの両方が対象です。サブエージェントは独立したコンテキストウィンドウを持つため、メインとは別のタイミングでcompactが走ります。プロンプトキャッシュの1時間TTLはメイン会話にしか適用されず、サブエージェントはサブスクリプションでも5分TTLのままです。

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

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

1Mトークンウィンドウのモデルでもcompactは起きますか

起きます。Fable 5、Sonnet 5、Opus 4.6以降、Sonnet 4.6のような1M対応モデルでも、ウィンドウが大きくなるだけでcompactの仕組み自体は変わりません。Sonnet 5はAPI直結であれば既定で約967Kトークンに達した時点でauto-compactが発火します。

まとめ

compactは、コンテキストウィンドウが埋まったときにClaude Codeが会話履歴を要約して空きを作る処理です。発火のしきい値はモデルと接続経路で4パターンに分かれ、単一の割合では語れません。要約後はCLAUDE.mdやAuto memoryのようにディスクから再注入されるものと、パス指定ルールやネストしたCLAUDE.mdのようにファイルが再度読まれるまで失われるものに分かれます。コストはキャッシュが温かいかどうかで大きく変わり、PreCompact・PostCompactフックを使えばcompactの前後に独自の処理を挟めます。溢れさせない運用としては、/contextやステータスラインでの可視化、サブエージェントへの委譲、CLAUDE.mdへの圧縮方針の記述が実務的な選択肢です。導入やモデル選び、権限設計まで含めたClaude Codeの全体像はClaude Code(クロードコード)とはにまとめてあります。