Claude Codeのセッション圧縮 — /compactの使い方と長時間運用の5つの習慣

このTipsでできること

長く開きっぱなしのセッションでは、応答の質が落ちるだけでなく、1回の質問に使われる量も増えます。Claude Codeは会話の全体を毎回のリクエストに載せるため、一行の質問でも、1日開いたセッションなら会話全体ぶんが使用量に数えられるからです。

原因は大きく3つあります。以下の5つの習慣は、いずれもこの3つのどれかを断つものです。

セッションを圧縮するには

セッションを圧縮するには、会話の途中で/compactを打ちます。それまでの会話が要約に置き換わり、同じ会話のまま続けられます。

何もしなくても、会話が圧縮ウィンドウに達すると自動で圧縮されます。ウィンドウの大きさは/autocompact 500kのように変えられます。

会話ごと捨てて空から始めたいときは/clearです。要約を残したいか、まっさらにしたいかで選びます。残るものの違いは習慣2、しきい値の設定は自動圧縮の節で扱います。

発火条件や要約後に残る情報の詳細はcompactとauto-compactの発火条件、ウィンドウの調整はautocompactの使い方にあります。ここでは長時間運用の習慣の中で、圧縮をどう使うかを扱います。

習慣1: 作業の切れ目で /clear を打つ

調査から実装へ、実装からレビューへと目的が変わるところで/clearを打ち、空のコンテキストから始め直します。公式docsも、無関係な作業へ移るときは/clearで新しく始めるよう案内しています。古いコンテキストは、後続のすべてのメッセージで余計なトークンになるためです。

/clear [name]のように名前を渡すと、直前の会話が/resumeの一覧にその名前で残ります。/renameで先に名前を付けてから消しても同じです。消したつもりの会話は、/resumeでいつでも戻れます。

/clearは会話を保たないので、引き継ぎたい状態は外に出しておきます。置き場所はgit logや作業メモのファイルです。/clearの前に/recapで一行要約を取り、メモに貼っておくと次のフェーズの最初のメッセージで渡しやすくなります。

/usageのコスト合計も/clearで0に戻ります。この挙動はv2.1.211からで、それ以前は同じプロセスの間、合計が積み上がり続けました。

習慣2: /compact には残したい内容を指示する

会話を捨てずに空きを作りたいときは/clearではなく/compactを使います。/compact Focus on code samples and API usageのように引数を渡すと、要約で優先して残す内容を指定できます。

毎回同じ指示を打つのが面倒なら、プロジェクトルートのCLAUDE.mdに書いておく方法があります。公式docsの例は次のとおりです。

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

圧縮後に何が残るかは、仕組みごとに違います。プロジェクトルートのCLAUDE.md、スコープ指定のないルール、auto memoryは、ディスクから読み直されて残ります。paths:付きのルールとサブディレクトリのCLAUDE.mdは、該当ファイルをまた読んだときに戻ります。

読んだファイルは、直近に変更した順で最大5件が読み直されます。5,000トークンを超えるファイルは本文なしのパス参照になり、画面にはReadでなくReferenced fileと出ます。

呼び出し済みのスキルの本文は、1スキルあたり5,000トークン、合計25,000トークンまでが再注入され、古いものから落ちます。一方、フックが以前に足した文脈は、会話の残りと一緒に要約されます。

どうしても毎回必要なルールは、paths:を外すか、プロジェクトルートのCLAUDE.mdに移すと、圧縮のたびに読み直されます。

習慣3: 大きなファイルはGrepで絞ってから読む

ファイルを丸ごと読むと、その全文がコンテキストに入ります。公式のコンテキストウィンドウ解説でも、ファイルの読み取りがコンテキスト消費で最も大きな割合を占めやすいとされています。

そこでGrepで該当箇所を探してから、必要な範囲だけReadします。指示も「auth.tsのバグを直して」のように具体的にすると、Claudeが読むファイルが減ります。

# 避けたい: 巨大ファイルを丸ごと読む
Read tools/big-config.ts
 
# 先に位置を絞る
Grep "exportConfig" tools/big-config.ts
Read tools/big-config.ts (offset と limit で範囲指定)

ログのように中身が大きい入力は、フックで前処理する方法もあります。10,000行のログからERRORの行だけを返すフックを置けば、数万トークンが数百トークンで済む、というのが公式docsの例です。

習慣4: 重い調査はサブエージェントに任せる

「リポジトリ全体を調べて」「過去100件のPRを分析して」といった作業は、メインの会話で直接やると中間の出力がすべて残ります。テストの実行、ドキュメントの取得、ログの処理も同じです。

これらをサブエージェントに任せると、冗長な出力はサブエージェント側の文脈に留まり、メインの会話には要約だけが返ります。調査用の組み込みサブエージェントExploreは、CLAUDE.mdとgit statusのスナップショットを読み込まない設計で、調査を速く安く回せます。サブエージェントを呼び出すツールは、v2.1.63でTaskからAgentに改名されました。設定やエージェント定義にあるTask(...)の記述は、エイリアスとしてそのまま動きます。使い分けはサブエージェント完全活用で扱っています。

逆の注意もあります。エージェントチームは、各メンバーが独立したコンテキストウィンドウを持つので、公式docsの見積もりではプランモードのチームが通常セッションの約7倍のトークンを使います。隔離は文脈を守りますが、使う量が減るわけではありません。

習慣5: 1セッション1目的にして、会話は枝分かれさせる

リファクタリング、新機能、テスト整備を1つの会話で進めると、関係のない履歴が互いの判断に混ざります。別々のターミナルか別のworktreeで並走させ、橋渡しは作業メモとgit logに寄せます。Worktree完全活用の物理的な隔離と組み合わせると、混線をファイルの層から断てます。

同じ文脈から別の方向を試したいだけなら、会話の複製が使えます。次の2つが入口です。

起動時のフラグにも対応するものがあります。claude --helpの出力から、関係する行だけ抜粋します。

-n, --name <name>      Set a display name for this session
                       (shown in the prompt box, /resume picker, and terminal title)
-r, --resume [value]   Resume a conversation by session ID,
                       or open interactive picker with optional search term
--fork-session         When resuming, create a new session ID
                       instead of reusing the original (use with --resume or --continue)
--autocompact <auto|tokens>
                       Auto-compact window size (auto, or 100k-1M tokens)

長く放置したセッションを再開するとき

数時間あけて同じセッションに戻ると、コストが跳ねることがあります。プロンプトキャッシュの有効期間は、サブスクリプションの範囲内のメイン会話で1時間です。usage creditsを使っている間は5分に縮み、APIキーやクラウドプロバイダーの利用では既定で5分です。

サブスクリプションでも、サブエージェントはメイン会話の枠の外なので5分です。環境変数は、ENABLE_PROMPT_CACHING_1H=1で1時間に、FORCE_PROMPT_CACHING_5M=1で5分に固定できます。

期間を過ぎたあとの最初のメッセージは、キャッシュに当たらず、会話全体を処理し直します。

ProまたはMaxで、約1時間を超えて空いた10万トークン超のセッションを再開すると、最初のメッセージを送る前に3択のダイアログが出ます。どれを選んでも、次のリクエストは全履歴を1回処理します。

放置中も使用量が動くことがあります。スケジュールタスクや、別セッションからのメッセージは、セッションが待機していても全文脈を送って新しいターンを始めます。目標(goal)の見張りも、待機中に最大3回まで確認のターンを起こします。

自動圧縮のしきい値を自分で決める

自動圧縮が走るのは、会話が圧縮ウィンドウに達したときです。設定は4か所にあります。

• /autocompact 500kのように値を渡す(v2.1.221以降。v2.1.288以降は現在のモデルについて保存され、それ以前は全モデル共通のautoCompactWindowに保存される)
• 設定ファイルのautoCompactWindow(全モデル共通)
• 起動時の--autocompact(v2.1.221以降。その起動だけ有効)
• 環境変数CLAUDE_CODE_AUTO_COMPACT_WINDOW(設定中は他のすべてより優先)

値は10万〜100万トークンで、環境変数は500kと書くと500と読まれて下限の10万に丸められます。整数で書きます。

早めに圧縮したいだけなら、CLAUDE_AUTOCOMPACT_PCT_OVERRIDEに1〜100の割合を入れる方法もあります。下げる方向にしか効かず、既定より大きい値は無視されます。逆にDISABLE_AUTO_COMPACT=1で自動圧縮を止めても、手動の/compactは使えます。

CLAUDE_CODE_DISABLE_1M_CONTEXT=1を設定すると、1Mが標準のモデルも200Kのコンテキストウィンドウとして扱われます。自動圧縮が有効なら200Kの境界で圧縮され、無効なら境界でコンテキスト上限のエラーになります。ウィンドウを200K超に設定しても、モデルのコンテキストウィンドウが上限なので持ち上がりません。

圧縮の前後にフックで手当てする

PreCompactフックは、圧縮の直前に走ります。マッチャーはmanual(/compact)とauto(自動圧縮)の2つです。

フックにはJSONが標準入力で渡され、trigger、custom_instructions、そして会話の記録ファイルを指すtranscript_pathが入っています。次の例は、その入力JSONをタイムスタンプ付きで保存します。

{
  "hooks": {
    "PreCompact": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "mkdir -p ~/.claude/snapshots && jq '.' > \"$HOME/.claude/snapshots/$(date +%Y%m%d-%H%M%S).json\""
      }]
    }]
  }
}

保存されるのは入力のメタ情報で、会話そのものではない点に注意が要ります。会話の記録を残したいなら、transcript_pathの指すファイルをコピーするコマンドに変えます。詳しいレシピはHooks実例カタログのレシピ8にあります。

PreCompactはexit code 2で圧縮を止められます。ただし、上限エラーからの回復のために走った自動圧縮を止めると、そのリクエストは失敗します。事前の自動圧縮なら、止めても会話は圧縮されずに続きます。

圧縮のあとに戻したい文脈には、SessionStartフックのcompactマッチャーが使えます。標準出力に書いた文字列がそのまま文脈に足されるので、「パッケージマネージャーはBunを使う」といった規約の再注入に向きます。

記録の書き込み失敗は「Transcript writes are failing」の対処で、/exportでの書き出しと保存先はセッションエクスポートとトランスクリプトの保存場所で扱っています。

どの習慣から入れるか

迷うなら、効きが大きく手間の小さい順で選びます。

1. 作業の切れ目で/clear(習慣1)。コストがかからず、導入が一番軽い
2. 重い調査のサブエージェント化(習慣4)。メインの履歴の増え方が変わる
3. Grep先行(習慣3)。大きなファイルを触る頻度が高い場合に効く
4. 1セッション1目的(習慣5)。並行作業が多い場合に効く
5. 圧縮の指示とフック(習慣2と圧縮の節)。長時間セッションが常態の場合に効く

どの順序が最も効くかは、作業の中身で変わります。使用量の内訳は/usageで確かめられます。Pro・Max・Team・Enterpriseのプランでは、長いコンテキストやキャッシュミスが直近の使用量の10%以上を占めると、内訳に出て対処のヒントが付きます。

まとめ

Claude Codeの長時間運用で効くのは、会話を小さく保つ工夫と、圧縮で消えるものを事前に外へ出す工夫の2系統です。まず/clearと/usageを日常に組み込み、それでも足りない所だけ圧縮設定とフックを足す順が無理がありません。

長時間セッションで起きがちな問題の全体像は、期待通りに動かない10シナリオを参照してください。48時間のような短期集中で履歴を回す例は、ゲームジャムでの運用にあります。