Claude プロンプトキャッシング完全ガイド — 5分 vs 1時間TTL選択戦略とコスト最適化の実践

# Messages APIでのcache_control設定例（デフォルト5分TTL）
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "あなたは技術文書のレビュアーです。...(長いシステムプロンプト)...",
            "cache_control": {"type": "ephemeral"}  # 5分TTL（デフォルト）
        }
    ],
    messages=[{"role": "user", "content": "このコードをレビューしてください"}]
)

# 1時間TTLを指定する場合
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "あなたは技術文書のレビュアーです。...(長いシステムプロンプト)...",
            "cache_control": {"type": "ephemeral", "ttl": "1h"}  # 1時間TTL
        }
    ],
    messages=[{"role": "user", "content": "このコードをレビューしてください"}]
)

通常コスト（キャッシュなし）: $0.30 / リクエスト
書き込みコスト: $0.30 × 1.25 = $0.375（初回のみ）
読み取りコスト: $0.30 × 0.1  = $0.03（2回目以降）

→ 2回目で累計 $0.405（通常2回 $0.60）→ 黒字化

書き込みコスト: $0.30 × 2.0 = $0.60（初回のみ）
読み取りコスト: $0.30 × 0.1 = $0.03（2回目以降）

→ 3回目で累計 $0.66（通常3回 $0.90）→ 黒字化

# 1時間TTLを有効化（長時間セッション向き）
export ENABLE_PROMPT_CACHING_1H=true
claude

# 5分TTLを明示指定（短いタスク向き）
export FORCE_PROMPT_CACHING_5M=true
claude

claude --verbose -p "このプロジェクトの構造を説明して"

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// 5分TTL（デフォルト）の例
const response = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 4096,
  system: [
    {
      type: "text",
      text: "あなたはコードレビューの専門家です。...(長い指示)...",
      cache_control: { type: "ephemeral" }, // ブレークポイント1: system（5分TTL）
    },
  ],
  tools: [
    {
      name: "analyze_code",
      description: "コードを静的解析する",
      input_schema: {
        type: "object" as const,
        properties: { code: { type: "string" } },
        required: ["code"],
      },
      cache_control: { type: "ephemeral" }, // ブレークポイント2: tools（5分TTL）
    },
  ],
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "以下のファイルをレビューしてください...(長いコード)...",
          cache_control: { type: "ephemeral" }, // ブレークポイント3: messages（5分TTL）
        },
      ],
    },
  ],
});

// 1時間TTLを使う場合は ttl パラメータを追加
// cache_control: { type: "ephemeral", ttl: "1h" }

console.log("書き込み:", response.usage.cache_creation_input_tokens);
console.log("読み取り:", response.usage.cache_read_input_tokens);
console.log("通常入力:", response.usage.input_tokens);

// キャッシュヒット率の計算
const total =
  (response.usage.cache_read_input_tokens ?? 0) +
  (response.usage.cache_creation_input_tokens ?? 0) +
  response.usage.input_tokens;
const hitRate = ((response.usage.cache_read_input_tokens ?? 0) / total) * 100;
console.log(`キャッシュヒット率: ${hitRate.toFixed(1)}%`);

# NG: 先頭に日時があるとキャッシュが効かない
system_prompt = f"現在時刻: {datetime.now()}\nあなたはコードレビューの専門家です..."

# OK: 静的な部分を先頭に、動的な部分を後ろに
system_prompt = "あなたはコードレビューの専門家です...\n" + f"現在時刻: {datetime.now()}"

import anthropic

client = anthropic.Anthropic()

def monitored_request(system_text: str, user_text: str):
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1024,
        system=[{
            "type": "text",
            "text": system_text,
            "cache_control": {"type": "ephemeral"}
        }],
        messages=[{"role": "user", "content": user_text}]
    )
    
    usage = response.usage
    created = getattr(usage, "cache_creation_input_tokens", 0) or 0
    read = getattr(usage, "cache_read_input_tokens", 0) or 0
    normal = usage.input_tokens
    
    print(f"通常: {normal} | 書込: {created} | 読取: {read}")
    
    if created > 0 and read == 0:
        print("→ キャッシュ新規作成（初回 or TTL切れ後）")
    elif read > 0:
        print(f"→ キャッシュヒット（削減率: {read / (read + normal) * 100:.0f}%）")
    else:
        print("→ キャッシュ未使用（最小トークン数未満の可能性）")
    
    return response