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

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

Compactionは、会話がトークン上限に近づくたびにClaudeが自動で古い文脈を要約し直す、Messages APIのサーバーサイド機能です。context_management.edits に compact_20260112 を渡すだけで有効になり、要約は compaction ブロックとしてレスポンスに埋め込まれます。既定の要約プロンプトはモデルごとに用意されていますが、instructions パラメータに文字列を渡すと、この既定プロンプトを完全に差し替えられます。

コーディングエージェントを長時間走らせていると、既定の要約では「次に何をすべきか」は残っても「どのファイルをどう変更したか」が薄くなることがあります。ドメイン固有の指示を注入して、要約に必ず残したい情報を明示するのがこの機能の使いどころです。

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

公式ドキュメントが例示するデフォルトプロンプトの一つは次のとおりです。

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 は context_management.edits の中の 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."
        }
      ]
    }
  }'

Python SDKでは context_management の edits に同じキーを渡すだけです。

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
 
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",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

この機能はベータ版で、anthropic-beta: compact-2026-01-12 ヘッダーが必須です。対応モデルはClaude Opus 5・Claude Sonnet 5・Claude Fable 5.1・Claude Mythos 5.1などで、Claude API・Amazon Bedrock・Google Cloud・Microsoft Foundry上のベータで使えます。

要約が生成されると、レスポンスの content の先頭に compaction ブロックが入り、それ以降のテキストブロックが続きます。次のリクエストではこのレスポンスをそのまま assistant メッセージとしてメッセージ配列に追加するだけで、APIが compaction ブロックより前の内容を自動的に無視し、要約から会話を継続します。instructions を変えても、この受け渡しの仕組み自体は変わりません。カスタムした要約の中身がどう変わるかだけに集中して実装できます。

使い分け早見表: デフォルトのままでよい場合とカスタムする場合

すべてのタスクで instructions を書く必要はありません。汎用的な会話やチャットボットのような用途では、デフォルトの要約プロンプトで十分機能します。ドメイン固有の情報を落とせないタスクだけ、カスタム化の効果が大きくなります。

表からも分かるとおり、判断基準は「圧縮後に何が失われると困るか」を具体的に言語化できるかどうかです。言語化できるなら、それをそのまま instructions の箇条書きに落とし込めます。

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

エージェントがリポジトリを横断編集するタスクでは、要約に「触ったファイルの一覧」と「未実行のコマンド」が残らないと、圧縮後にClaudeが同じファイルを読み直したり、変更を重複させたりします。ここに instructions でドメイン指示を注入します。

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.
"""
 
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文で済ませず、番号付きリストで要求する情報の形まで指定しているのがポイントです。自由記述の指示だとClaudeが要約の中で優先順位を付け直してしまい、ファイル一覧が省略されることがあります。番号付きリストで固定フォーマットを要求すると、要約のたびに同じ構造で情報が残ります。

上書き時に気をつける落とし穴

• 「補う」ではなく「置き換える」: instructions はデフォルトプロンプトに追記されるのではなく、完全に差し替わります。デフォルトが暗黙に頼っていた指示(<summary> タグで包む、等)が必要なら、自分の instructions にも明示的に書く必要があります。上の例で <summary></summary> を明記しているのはこのためです
• Claude Fable 5.1・Claude Mythos 5.1では思考ブロックが要約対象に入らない: この2モデルでカスタム instructions を使うと、要約は可視の会話だけから作られます。それ以前の思考ブロックは要約の材料にならないため、「思考の過程で決めた設計判断」を残したいなら、その判断を可視のテキスト応答としても書かせておく必要があります
• 要約プロンプトを凝りすぎない: 指示が長すぎると要約自体のトークン消費が増え、圧縮の効果を薄めます。残したい項目を絞り、番号付きリストで簡潔に書くのが実用的です
• トリガーとの組み合わせを忘れない: instructions は要約の中身を決めるだけで、いつ要約するかは trigger.value(既定150,000トークン、最小50,000トークン)が別に決めます。頻繁に変更ファイルが増えるタスクでは、トリガーの閾値を下げて要約頻度を上げるほうが情報の取りこぼしが減ることがあります
• 番号付きリストの項目を増やしすぎない: 「残してほしい情報」を10個以上並べると、Claudeがどれを優先するか迷い、結局全部が薄く書かれることがあります。本当に落とせない項目だけを3〜5個に絞り込むほうが、実際の要約品質は安定します

要約の品質は実際に長時間タスクを走らせて確認するまで分かりません。instructions を変更したら、圧縮が発生する手前のタスクで一度実行し、生成された compaction ブロックの中身を目視で確認してから本番運用に載せるのが安全です。とくに番号付きリストの各項目が実際に埋まっているか、空欄のまま通っていないかは、最初の数回は必ず確認する価値があります。

よくある質問

instructionsは会話が続く限り毎回渡す必要があるか

はい。context_management.edits はリクエストごとに評価されるパラメータなので、instructions を1回のリクエストに書いても、それが以降の会話に自動で引き継がれることはありません。長時間タスクの間ずっとカスタム要約プロンプトを使いたい場合は、messages を組み立てるコードの中で、context_management を毎回同じ内容で組み立てる必要があります。定数として切り出して使い回すのが実務上の定石です。

圧縮が発生しなかったリクエストでinstructionsはどう扱われるか

trigger.value に達していないリクエストでは圧縮そのものが起きないため、instructions は単に評価されず何の効果も持ちません。カスタム要約プロンプトを設定しても、それだけでレスポンスの速度や内容が変わることはなく、実際に圧縮が発火したときにだけ使われます。

複数のドメイン(コーディングと調査を両方扱うエージェント)ではどうするか

1つのエージェントがコーディングタスクと調査タスクを両方扱う場合、instructions を1本に固定するとどちらかの要件が薄まります。実務では、タスクの種類をエージェント側で判定し、context_management を組み立てる直前に instructions の文字列を切り替える実装が現実的です。「今このセッションはコーディングタスクか、調査タスクか」を判定するロジック自体はCompactionの外側にあるため、既存のタスク分類ロジックにそのまま乗せられます。共通の骨格(番号付きリストで残す項目を明示する、<summary> タグで包む)は使い回し、リストの中身だけをタスク種別ごとに用意しておくと保守しやすくなります。

TypeScriptでも同じキーで実装できるか

できます。context_management.edits のキー名はSDKをまたいで共通で、instructions もそのまま string として渡します。

const 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.
2. Commands that were run and their outcome (pass/fail).
3. Commands that still need to be run.
Wrap the summary in a <summary></summary> block.
`;
 
const response = await client.beta.messages.create({
  betas: ["compact-2026-01-12"],
  model: "claude-opus-5",
  max_tokens: 4096,
  messages,
  context_management: {
    edits: [
      {
        type: "compact_20260112",
        trigger: { type: "input_tokens", value: 100000 },
        instructions: CODING_TASK_SUMMARY_INSTRUCTIONS,
      },
    ],
  },
});

TypeScript SDKでもキー名はPythonと同じsnake_caseのままで、違いはawaitを伴う呼び出し形式だけです。instructions の設計方針自体はどちらの言語でも変わりません。

まとめ

Compactionのデフォルト要約プロンプトは汎用的な「進捗の継続」を狙った文面で、コーディングタスク特有の情報(変更ファイル・実行済みコマンド・設計判断)を名指しでは要求しません。instructions パラメータに番号付きリストでドメイン指示を書くと、要約のたびに同じ構造で必要な情報を残せます。ただし指示は既定プロンプトを完全に置き換える点と、Claude Fable 5.1・Claude Mythos 5.1では思考ブロックが要約の材料に入らない点は、実装前に把握しておく必要があります。要約が発火するタイミングの制御はエージェントループの内部モデルを理解しておくと設計しやすくなります。長時間タスクの文脈管理全体の考え方はAnthropicのコンテキストエンジニアリング論、プロンプトキャッシュとの併用はdefer_loadingの仕組みも参考になります。