Prompt Cachingの「プレフィックス原則」を理解する — cache_controlブレークポイントの配置戦略とツール定義キャッシュの実務的メリット

はじめに

Claude API の Prompt Caching を使っていて、こんな経験はないでしょうか。

「システムプロンプトの末尾と tools ブロックの末尾に cache_control ブレークポイントを2つ置いた。ユーザーメッセージだけ変えればどちらもキャッシュヒットする。でも、システムプロンプトを1行編集しただけで、tools 側までキャッシュミスになった。なぜ？」

この疑問を掘り下げていくと、Prompt Caching の根本原則である 「プレフィックス単位のキャッシュ」 という仕組みに行き着きます。本記事では、この原則を理解した上で、ブレークポイントの配置戦略やツール定義キャッシュの重要性について整理します。

Prompt Caching は「プレフィックス」で動く

キャッシュの基本原則

Prompt Caching は、プロンプトの先頭から順番に内容をハッシュし、一致する部分をキャッシュとして再利用する仕組みです。ここで重要なのは、各ブレークポイントが独立してキャッシュされるのではなく、先頭からそのブレークポイントまでの累積的な内容がキャッシュキーになるという点です。

ドミノ倒しの原理

この「プレフィックス原則」により、前方のブロックが変更されると、後続のすべてのキャッシュが無効化されます。

• ブレークポイント①のキャッシュキー: hash(システムプロンプト)
• ブレークポイント②のキャッシュキー: hash(システムプロンプト + tools ブロック)

システムプロンプトが1文字でも変わると、ブレークポイント①のハッシュが変わり、連鎖的にブレークポイント②のハッシュも変わります。tools ブロックの内容が同一であっても、プレフィックスが異なるため新しいキャッシュキーとして扱われるのです。

リクエストペイロードで見るキャッシュの挙動

リクエスト1: キャッシュの作成

{
  "model": "claude-sonnet-4-20250514",
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant. [長いシステムプロンプト...]",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "指定された都市の天気情報を取得する",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "都市名" },
          "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
        },
        "required": ["city"]
      },
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "東京の天気を教えて" }
  ]
}

このリクエストで、2つのブレークポイントが作成されます。

リクエスト2: ユーザーメッセージのみ変更（キャッシュヒット）

{
  "messages": [
    { "role": "user", "content": "大阪の天気は？" }
  ]
}

システムプロンプトと tools が同一 → 両方キャッシュヒット。

リクエスト3: システムプロンプトを1行編集（キャッシュミス）

{
  "system": [
    {
      "type": "text",
      "text": "You are an expert assistant. [長いシステムプロンプト...]",
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

helpful → expert に変更しただけで：

ブレークポイント②の tools ブロックは変更されていないのに、プレフィックスが変わったためキャッシュミスになっています。

「tools は名前だけ」は誤解 — ツール定義のキャッシュが重要な理由

「ツールなんて名前だけでしょ？ キャッシュする意味あるの？」と思うかもしれません。実際にはツール定義は想像以上に「重い」データです。

ツール定義の実態

ツールは名前だけでなく、完全なJSON Schema定義を含みます。

{
  "name": "search_database",
  "description": "顧客データベースを検索し、フィルタ条件に基づいて結果を返す。ページネーション対応。",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "検索クエリ文字列"
      },
      "filters": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["active", "inactive", "suspended"]
          },
          "created_after": {
            "type": "string",
            "format": "date-time"
          },
          "region": {
            "type": "string",
            "enum": ["us-east", "us-west", "eu", "ap"]
          }
        }
      },
      "page": { "type": "integer", "minimum": 1 },
      "page_size": { "type": "integer", "minimum": 1, "maximum": 100 }
    },
    "required": ["query"]
  }
}

1つのツール定義で200〜500トークンを消費します。本番のエージェントが20個のツールを持っていれば、毎リクエスト4,000トークン以上がツール定義だけで使われます。

キャッシュの有無で変わるコスト

10ツール・合計2,000トークンのケース：

短いユーザーメッセージに対して毎回4,000トークンのツール定義を処理し直すのは、コスト面でもレイテンシ面でも非効率です。キャッシュすることで、ツール定義は実質的に「一度書き込んで、何度も安く読む」運用になります。

ブレークポイント配置の「Stable to Fluid」原則

プレフィックス原則を理解すると、最適な配置戦略は明確になります。変わらないものほど前方に、変わるものほど後方に配置する「Stable to Fluid（安定→流動）」原則です。

推奨する配置順序

よくあるアンチパターン

実務での判断基準

• システムプロンプトが安定している場合: ①②の2つのブレークポイントで十分。毎リクエストでユーザーメッセージだけが変わるため、高いヒット率が期待できる
• Few-shot例やRAG文脈がある場合: ③も追加することで、会話履歴やユーザーメッセージの変更に影響されずにキャッシュを維持できる
• 開発・デバッグ中: システムプロンプトの変更が頻繁なため、キャッシュヒット率は低くなる。これは想定内であり、本番デプロイ後に効果が出る

まとめ

Prompt Caching を効果的に使うための要点を整理します。

1. プレフィックス原則を理解する: キャッシュは先頭からの累積ハッシュで管理される。前方の変更は後続すべてのキャッシュを無効化する
2. ツール定義は「重い」: 名前だけでなくJSON Schema全体がトークンを消費する。20ツールで4,000トークン超のオーバーヘッドになり得る
3. Stable to Fluid で配置する: 静的なものほど前方に、動的なものほど後方に。これがキャッシュヒット率を最大化する基本戦略
4. 本番で効果が出る: 開発中のプロンプト変更はキャッシュミスを招くが、プロンプトが安定した本番環境でこそコスト削減とレイテンシ改善の効果が最大化される

Prompt Caching は「動画ファイルのチェックサム」に似ています。先頭10秒を変えれば、ファイル全体のチェックサムが変わり、プレイヤーは最初から読み直す必要があります。この比喩を覚えておけば、キャッシュの挙動で迷うことは少なくなるはずです。