プロンプトキャッシュはClaude Codeの利用上限をどう軽くするか
プロンプトキャッシュはClaude Codeの5時間枠と週次上限の消費を、読み取り分の安い単価だけ軽くします。何が壊れ、どう観測し、TTLをどう選ぶかを仕様から説明します。
Claude Codeは会話の全履歴を毎ターン送り直します。プロンプトキャッシュが効いていれば、その再送分はキャッシュ読み取りの単価で処理され、5時間枠と週次上限の消費もその分だけ軽くなります。読み取り単価は通常の入力トークンのおよそ10%です。ただしキャッシュはモデル切り替えなどの操作で簡単に壊れ、壊れた直後の1ターンは通常単価に戻ります。
プロンプトキャッシュは利用上限の消費をどう軽くするか
Claude Codeは新しいメッセージを送るたびに、システムプロンプト・プロジェクトコンテキスト・それまでの会話履歴をまるごと1つのリクエストとして送信します。新規部分は末尾に追記されるだけなので、直前のリクエストと先頭が一致する部分(プレフィックス)はAPI側のキャッシュから読み直せます。
プレフィックスが一致した分は「キャッシュ読み取り」として扱われ、通常の入力トークンよりおよそ10%の単価で処理されます。5時間枠(セッション枠)と週次上限はどちらもサブスクリプションの消費量として計測されるため、同じ会話を続けていても、読み取り単価が安い分だけ上限に当たる頻度が下がります。長時間の会話ほど、この差は効いてきます。
ここで扱うのは会話プレフィックスを再利用するプロンプトキャッシュです。WebFetchが取得したページ自体は15分の別キャッシュで管理され、独立した仕組みです(Claude Code WebFetchのキャッシュとタイムアウト)。Anthropic API全般でのコスト削減の基本原理はAnthropic APIのPrompt Cachingを理解するにまとめてあります。API課金とサブスクリプションの利用上限は消費のされ方が別なので、節約効果もここで改めて確認する必要があります。
何がキャッシュを壊し、消費を増やすか
キャッシュが壊れる操作の多くは、システムプロンプトかツール定義の中身を変えるものです。壊れると次のリクエストは会話全体を再処理するため、その1ターンだけ通常単価の消費に戻ります。
| 操作 | キャッシュへの影響 | 消費への効き方 |
|---|---|---|
/modelでのモデル切り替え | キャッシュへの影響全損(モデルごとにキャッシュが別) | 消費への効き方明確に増える(切り替え直後の1ターンのみ) |
| エフォートレベルの変更 | キャッシュへの影響全損(Fable 5.1のサブスク/APIキー利用を除く) | 消費への効き方明確に増える |
| fast modeのオン | キャッシュへの影響全損 | 消費への効き方セッション開始直後は小さく、長時間セッションの途中では大きい |
| MCPサーバーの接続・切断 | キャッシュへの影響ツール定義がプレフィックスに直接読み込まれている場合のみ全損 | 消費への効き方環境依存(既定のtool searchで遅延読み込みされていれば影響なし) |
| ツールを丸ごと拒否するdenyルールの追加 | キャッシュへの影響全損 | 消費への効き方小さいが見落としやすい |
/compact(要約への圧縮) | キャッシュへの影響会話層のみ再構築 | 消費への効き方中程度(要約リクエスト自体はキャッシュ読み取りで安く済む) |
| 大量の画像蓄積によるバッチ削除 | キャッシュへの影響削除した画像を含むメッセージ以降を再構築 | 消費への効き方画像を多用するセッションで中程度 |
| Claude Codeのアップグレード後の初回ターン | キャッシュへの影響全損(システムプロンプトが更新される) | 消費への効き方起動直後の1ターンだけ大きい |
| プラグインの有効化・無効化 | キャッシュへの影響skills/commands/agents/hooks/monitors/themesは維持。MCPサーバーを提供するプラグインはMCPサーバーの接続・切断と同じ規則 | 消費への効き方プラグインの種類次第(維持されればゼロ、MCP系は環境依存) |
次の操作は、会話の末尾に追記するだけか会話自体に触れないため、キャッシュを維持したまま消費を増やしません。
- ファイルの編集
- CLAUDE.mdの編集(次のセッションまで反映されない)
- 出力スタイルの変更
- 権限モードの切り替え
- スキルやコマンドの呼び出し
/recap/rewind(既にキャッシュ済みのプレフィックスまで巻き戻すだけなので、むしろ安全な操作です)- サブエージェントの起動
アイドル中でも上限を消費する要因
会話を開いたまま何も入力していなくても、Claude Codeが新しいターンを発生させることがあります。アイドル中の新規ターンは、キャッシュが冷えていれば通常単価の消費に戻ります。
- スケジュールタスク:
/loopなどの定期実行タスクは、セッションがアイドルでも設定した間隔で発火し、そのたびに全コンテキストを送信します - クロスセッション通知: 別セッションからのメッセージは、このセッションがアイドルのときも新しいターンとして届き、全コンテキストを送り直します。
crossSessionInboundをholdに設定すれば、アイドル中の配信を保留できます - ゴールのチェックイン: バックグラウンド作業がアクティブな目標を待たせているあいだ、Claude Codeは1つの目標につき最大3回までアイドル中の状態確認を挟みます(
CLAUDE_CODE_GOAL_CHECKIN_MINUTESを0にすると無効化できます) - Agent teammates: エージェントチームでは、アクティブなteammateが1体でもいるとそれが自発的に終了するまでトークン消費が続きます。セッション自体がアイドルでも、teammateが動いている限り消費は止まりません
いずれも、アイドル時間がキャッシュのTTLを超えていれば通常単価の全損ミスとして処理されます。心当たりのない5時間枠の消費を見つけたときは、この4つを疑う価値があります。
Pro・Maxの利用上限とTTLの関係
rate_limitsオブジェクト(5時間枠・週次上限・使用量クレジットの上限)は、誰にでも見えるわけではありません。Claude.ai Pro・Maxのサブスクリプション利用者か、支出上限を設定されたClaude appsゲートウェイ経由でだけ現れます。5時間枠と週次上限の基本的な仕組みはClaude Pro制限の仕組みが扱い、本節ではキャッシュのTTL(有効期間)がその消費とどう結びつくかに絞ります。
TTLは会話ごとではなく、リクエストの種類ごとに2つのバケットへ分かれます。
| リクエストの種類 | プラン内消費(サブスク) | 使用量クレジット・APIキー・クラウドプロバイダー |
|---|---|---|
メイン会話(対話ターン・-p実行・Agent SDK) | プラン内消費(サブスク)1時間 | 使用量クレジット・APIキー・クラウドプロバイダー5分 |
| それ以外(サブエージェント・ワークフロー・compaction等) | プラン内消費(サブスク)5分(一部のサーバー制御ヘルパーのみ1時間) | 使用量クレジット・APIキー・クラウドプロバイダー5分 |
プラン内消費のあいだだけ、メイン会話は1時間キャッシュが温かいままです。5時間枠か週次上限を使い切って使用量クレジットへ入ると、Claude Codeはメイン会話のTTLを自動的に5分へ落とします。離席を挟んでも壊れにくかったキャッシュが、上限超過を境に壊れやすくなるということです。この切り替えは自動で行われます。ステータスラインのttlが5mに変われば見分けられます(確認方法は後述)。
可用性はサブスクリプション経由に限られます。Amazon BedrockやGoogle Cloud's Agent Platform、Claude appsゲートウェイ経由では1時間TTLの選択自体ができません。
どう観測するか — /usageとステータスライン
/usageはメイン会話の初回応答後、セッションブロックに次のようなPrompt cache (main)行を追加します(Claude Code v2.1.251以降)。
Prompt cache (main): 14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)「miss」は、キャッシュから読めたはずの5%かつ2,000トークンを超える量を再処理したリクエストを指します。「expected rebuild」は/compactやツール結果のクリアが原因の再構築で、通常のmissとは区別されます。この行はメイン会話だけを対象にし、サブエージェントの消費は含みません。/clearでセッションブロックごとリセットされます。
同じ数値はステータスラインのprompt_cacheオブジェクトからも読めます(Claude Code v2.1.251以降)。
| フィールド | 意味 |
|---|---|
warm | 意味キャッシュされたプレフィックスがまだTTL内かどうか |
hit_ratio | 意味全入力トークンに占めるキャッシュ読み取りの割合(0〜1) |
misses | 意味ミスと判定されたリクエスト数 |
ttl | 意味現在のプレフィックスに適用されているTTL("5m"または"1h") |
claude -p "hello" --output-format json | jq '.usage.cache_creation'このコマンドでephemeral_1h_input_tokensとephemeral_5m_input_tokensのどちらにキャッシュ書き込みが計上されたかを確認できます。1時間TTLで書き込まれていれば、サブスクリプションのプラン内消費のまま処理されている証拠です。
/usageのプラン消費内訳では、長いコンテキストやキャッシュミスのような挙動が直近使用量の10%以上を占めると「Behavior flags」として表示されます。利用上限の警告メッセージそのものの種類と見分け方はClaude Codeの利用上限にまとめてあります。
TTLを自分で選ぶ設定
TTLは明示的に設定できます(Claude Code v2.1.242以降)。APIキーやクラウドプロバイダー経由でメイン会話を1時間キャッシュにしたい場合や、使用量クレジットに入っても1時間TTLを維持したい場合に使います。
{
"promptCacheTtl": "1h",
"subagentPromptCacheTtl": "1h"
}環境変数でも同じ指定が可能です。
CLAUDE_CODE_PROMPT_CACHE_TTL=1h claude優先順位は次の順です。上にあるものほど強く効きます。
FORCE_PROMPT_CACHING_5M=1(両バケットを強制的に5分に)- 各バケットの環境変数
- 各バケットの設定
- サブエージェントの
experimental.cacheTtlフロントマター(v2.1.248以降)。ただしサブスクリプションが使用量クレジットを消費中は、ここに1hを指定してもClaude Codeは無視します ENABLE_PROMPT_CACHING_1H=1(両バケットを1時間に)- リクエストの種類ごとの既定値
プロンプトキャッシュの節約はプラン内消費の間だけ最大化する
プロンプトキャッシュが利用上限を軽くする効果は、常に一定ではありません。サブスク利用者が1時間TTLの恩恵を受けられるのは、5時間枠と週次上限のどちらも使い切っていない、プラン内消費のあいだだけです。使用量クレジットに入った瞬間、Claude CodeはメインのTTLを5分へ落とし、離席のたびにキャッシュが壊れやすくなります。
つまり、キャッシュによる節約は上限に近づくほど薄くなる設計です。上限へ当たりやすい使い方(長時間セッションを毎日回す、fast modeやモデル切り替えを頻繁に行う)ほど、その節約が失われるタイミングも早く訪れます。上限に当たる前に一区切りつけて/clearや/compactを挟むという選択肢もあります。
よくあるつまずき
opusplanのモデル設定は、プランモードと実行モードを行き来するたびにOpusとSonnetを切り替えます。これはモデル切り替えそのものなので、往復のたびにキャッシュが壊れます。プランモードを多用するワークフローでは、この切り替えコストが積み上がりやすい点に注意してください。
長期間放置したセッションを--resumeで再開すると、Claude Codeをアップグレードしていた場合はシステムプロンプトが変わっているため、会話履歴全体がキャッシュなしで再処理されます。Pro・Maxプランでは、長いセッションを長期間放置後に再開しようとすると要約からの再開を提案されるため、この重い再処理を避けられます。
サブエージェントとワークフローのファンアウトはメイン会話のTTLバケットの外にあり、サブスクリプションでも既定は5分です。ファンアウト内で同じプレフィックスを持つエージェント同士がキャッシュを共有できる条件はClaude Codeワークフローのプロンプトキャッシュの効き方で扱っています。
git worktreeは同じリポジトリでも作業ディレクトリが別なので、それぞれが独立にキャッシュを温め直します。worktreeを増やして並行作業するほど、上限への当たり方はworktreeの数だけ重なります。同じディレクトリで並列に開いた複数セッションはキャッシュを共有できますが、順番に開くセッション同士はブランチや直近コミットを含むgitステータスが一致するときしか共有できません。
まとめ
プロンプトキャッシュは、5時間枠と週次上限の消費をキャッシュ読み取りの安い単価分だけ軽くする仕組みです。効果を維持する条件は、キャッシュを壊す操作(モデル切り替え・エフォート変更・MCP接続変化など)を避けることと、プラン内消費のうちに1時間TTLの恩恵を使い切ることの2つです。/usageのPrompt cache (main)行かステータスラインのprompt_cacheオブジェクトを見れば、いま自分のセッションがどちらの状態にあるかを確認できます。