Compactionのカスタム要約プロンプトを書く実装ガイド

Compactionのカスタム要約プロンプトとは

Compactionは、長い会話の古い部分をClaudeが要約に置き換えるMessages APIのサーバーサイド機能です。要約の書き方は instructions に文字列を渡して変えられます。渡した文字列は既定の要約プロンプトに足されるのではなく、完全に置き換えます。

instructions を受け取る入口は2つあります。トークン数が閾値に達したらAPIが自動で要約する「閾値型」(context_management.edits の compact_20260112)と、アプリ側が好きなタイミングで要約を依頼する「オンデマンド型」(トップレベルの compaction パラメータ)です。どちらを使うかで、要約に使われる材料や指示の長さ制限が変わります。

コーディングエージェントを長時間走らせるなら、どちらの型でも「次にやること」だけでなく「どのファイルをどう変えたか」を明示的に要求しておく価値があります。クライアント側で自前の要約プロンプトを書く場合の考え方は、Claude Fable 5.1の保持指示でcompactionの要約を書く方法にまとめています。

デフォルトの要約プロンプトはどう書かれているか

既定のプロンプトはモデルごとに違います。公式ドキュメントが例に挙げているものの一つは次のとおりです。

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

「状態・次の手順・学びなど役に立つことは何でも書く」という汎用の指示です。変更したファイルのパス、未実行のテストコマンド、設計判断の理由といった項目は名指しされていません。既定の要約で後続のターンに必要な情報が落ちたと気づいたときが、instructions を書き始めるタイミングです。

閾値型でinstructionsを渡す

閾値型では instructions を compact_20260112 エディットに文字列で渡します。既定値は null で、値を渡した時点から既定プロンプトは使われません。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: compact-2026-01-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 4096,
    "messages": [
      {"role": "user", "content": "Hello, Claude"}
    ],
    "context_management": {
      "edits": [
        {
          "type": "compact_20260112",
          "instructions": "Focus on preserving code snippets, variable names, and technical decisions."
        }
      ]
    }
  }'

要約が生成されると、レスポンスの content の先頭に compaction ブロックが入り、そのあとにテキストブロックが続きます。次のリクエストでは、このレスポンスを assistant メッセージとして配列に足すだけで、APIが compaction ブロックより前の内容を無視して要約から続けます。instructions を変えても、この受け渡しは同じです。

対応モデルは、Claude Fable 5.1・Mythos 5.1・Opus 5.5・Sonnet 5.5と、それ以前のOpus 5・Sonnet 5などです。提供先はClaude API・Claude Platform on AWS・Amazon Bedrock・Google Cloud・Microsoft Foundryのベータです。

オンデマンド型でinstructionsを渡す

オンデマンド型は、要約のタイミングをコード側で決めたいときの入口です。公式の例では、要約の対象と最後の未解決の依頼を具体的に書いたうえで、ツールを呼ばないよう指示しています。

{
  "compaction": {
    "type": "summarize",
    "instructions": "Summarize this recipe app design conversation. Preserve every entity and field name agreed so far, and the user's latest open request. Do not call tools; respond with the summary text only."
  }
}

要約を依頼するリクエストと、署名つきのブロックを含む以降のリクエストのすべてに、compact-2026-09-04 ヘッダーが必要です。直近のターンを逐語で残す方法は、公式のCompaction that keeps recent turnsにあります。

コーディングタスク向けに変更ファイル一覧を必ず残す

リポジトリを横断して編集するタスクでは、触ったファイルの一覧と未実行のコマンドを要約に残すよう指示します。以下は閾値型の例です。

CODING_TASK_SUMMARY_INSTRUCTIONS = """\
Summarize the transcript so a future context window can resume this coding task
without the raw history. Your summary MUST include, as explicit lists:
 
1. Every file path that was created, edited, or deleted, with a one-line
   description of what changed in each.
2. Commands that were run and their outcome (pass/fail), especially test
   and build commands.
3. Commands that still need to be run before the task is considered done.
4. Any design decision that deviated from the original request, and why.
 
Do not omit a file from the list even if the change was small. Wrap the
summary in a <summary></summary> block. Do not call any tools; respond with
text only.
"""
 
client = anthropic.Anthropic()
 
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 100000},
                "instructions": CODING_TASK_SUMMARY_INSTRUCTIONS,
            }
        ]
    },
)

指示は「ファイル一覧は残す」と1文で済ませず、番号付きで残す情報の形まで書いています。<summary></summary> タグで包む指示も自分で入れてください。既定プロンプトに含まれていた指定は、置き換えると一緒に消えます。

ツールを定義していると要約が空になることがある

見落としやすいのが、リクエストに tools を含めているケースです。閾値型では、要約を書く内部ステップでモデルがテキストの代わりにツールを呼ぶことがあり、そのとき compaction ブロックの content が null になります。公式の対処は、ツールを呼ばないよう instructions に明記することです。上のコーディング用プロンプトの最終行はこのためです。

オンデマンド型では、同じ失敗が stop_reason: "tool_use" と空の content を持つ200レスポンスとして返ります。ほかの失敗も stop_reason で見分けられます。

要約の費用はどこに出るか

要約の呼び出しは通常のリクエストと同じく課金され、レート制限の対象です。オンデマンド型では、使用量が usage.iterations の compaction エントリに出ます。返信を生成していないため、トップレベルの input_tokens と output_tokens は0になります。会話全体の消費量は、トップレベルではなく usage.iterations を合計して数えます。

要約に使われるモデルは、リクエストで指定したモデルそのものです。要約だけ安いモデルに任せる選択肢は、閾値型にはありません。

上書きするときの落とし穴

• 「補う」のではなく「置き換える」: 既定プロンプトが暗黙に担っていた指定(<summary> タグで包む、など)は、自分の instructions にも書きます。
• 思考の途中で決めた設計判断は、可視のテキストにも書かせる: 閾値型の要約には思考ブロックが入らない場合があります(前掲の比較のとおり)。オンデマンド型は逆に、思考ブロックを含めて要約します。
• 要約の発火は instructions と別に決まる: 閾値型では trigger.value が時期を決めます。変更が速く積み上がるタスクで取りこぼしが気になるなら、50,000以上の範囲で閾値を下げる手があります。
• 指示は短く保つ: オンデマンド型の上限は前掲の数字表のとおりです。超えそうなら残す項目を絞ります。圧縮後に何が失われると困るかを言語化できれば、それがそのまま箇条書きになります。
• 要約に載らない内容がある: オンデマンド型の公式ページによると、要約された範囲の画像・ドキュメント・取得したURLの内容はブロックに置き換わった時点で消えます。後続のターンで必要なら、instructions で書き出させるか、再度渡します。

instructions を変えたら、圧縮が起きる直前まで会話を進めて、生成された compaction ブロックの中身を読みます。番号付きリストの各項目が実際に埋まっているかを、最初の数回は確かめてください。ブロックには cache_control を付けてブレークポイントを置けるので、キャッシュの扱いはdefer_loadingの仕組みのようなプロンプトキャッシュの記事と合わせて設計します。

よくある質問

instructionsは毎回渡す必要があるか

閾値型の context_management.edits は通常リクエストのパラメーターなので、要約を発火させたいリクエストには毎回付ける形になります。定数に切り出して、リクエストを組み立てる関数から使い回すのが扱いやすい構成です。

コーディングと調査を両方扱うエージェントではどうするか

instructions を1本に固定すると、どちらかの要件が薄まります。タスクの種類を判定する処理はCompactionの外側にあるので、context_management を組み立てる直前で文字列を切り替えます。「番号付きで残す項目を明示する」「<summary> で包む」「ツールを呼ばせない」の骨格は共通にして、リストの中身だけをタスク別に用意すると保守しやすくなります。

まとめ

発火のタイミングをAPIに任せるなら閾値型、コード側で握りたいならオンデマンド型です。tools を持つエージェントでは、最初に圧縮直前まで会話を進め、compaction ブロックが空でないことを確かめてください。

要約を発火するタイミングの制御は、エージェントループの内部モデルを押さえておくと設計しやすくなります。長時間タスクの文脈管理全体の考え方はAnthropicのコンテキストエンジニアリング論にあります。