Claude Code のプロンプトキャッシュの仕組み:効く操作・切れる操作

公開: 2026年10月15日 ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

仕組み:リクエストの先頭が一致した分を再利用する

以下は執筆時点(2026年10月)の公式ドキュメントの記述にもとづく整理で、私が試した結果ではありません。公式ドキュメントによると、モデルはリクエスト間で何も記憶しないため、Claude Code は毎回、システムプロンプト、プロジェクトの文脈、過去のメッセージとツール結果、新しいメッセージの全体を送り直します。新しい内容は末尾に足されるので、大半は直前と同じです。

API は、リクエストの先頭(プレフィックス)を最近処理した内容と照合して再利用します。照合は完全一致で、途中のどこかが変わるとそれ以降はすべて再計算されます。ファイル単位のキャッシュはありません。再利用分はキャッシュ済みトークンの料金で課金されます。

変わりにくい順に、次の3層で並びます。

• システムプロンプト:基本の指示とツール定義。ツール定義の集合が変わると変化します。
• プロジェクトの文脈:CLAUDE.md、auto memory など。セッション開始時と、/clear・/compact の後に変化します。
• 会話:メッセージ、応答、ツール結果。毎ターン変化します。

会話層の変更ならほかの2層はキャッシュに残りますが、システムプロンプトが変わると全体が無効になります。このほかモデルごとにキャッシュは別で、多くのモデルでは effort レベルごとにも別です。

出典: How Claude Code uses prompt caching

切れる操作:モデル切り替え・ツール定義の変更・/compact など

切れると、次のターンだけ遅く高くつき、その後は新しいプレフィックスがキャッシュされます。

モデルと effort、fast mode

/model でモデルを切り替えると、内容が同じでも次のリクエストは履歴全体をキャッシュなしで読みます。ターミナルでは、キャッシュが温かく、かつ切り替え先が直前の応答を生成したモデルでない場合だけ確認が出ます。opusplan ではプランモードの切り替えごとに、frontmatter で別の model を指定した skill やコマンドではそのターンが、モデル切り替えになります。

effort の変更も多くのモデルで同様です。ただし Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.1 を API キーか Claude サブスクリプションで使う場合はキャッシュが保たれます。Amazon Bedrock、Google Cloud の Agent Platform、Claude apps gateway、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 設定時、HIPAA 構成の組織では対象外です。

fast mode をオンにすると、最初のリクエストがキャッシュなしになります。コストは会話ごとに1回で、セッション序盤にオンにするほど安く済みます。

ツール定義

ツール定義はシステムプロンプト層にあるため、集合が変わると無効になります。MCP のツール検索がツールを遅延読み込みしている場合(対応モデルでの既定)は、サーバーの接続・切断で影響しません。ツール検索が無効などでツールを先頭から読み込む場合は、定義の追加や、deny ルール・/mcp での無効化による削除で無効になります。ツール検索が使えないか無効な場合は、ツール名だけの deny ルール(Bash など)を加えると次のリクエストから定義が削除され、キャッシュが無効になります。Bash(rm *) のような範囲指定の deny ルールや allow・ask ルールは影響しません。

圧縮とその他

/compact は履歴を要約に置き換えるため、会話層が無効になります。ただし要約の依頼はキャッシュが温かければプレフィックスを読むので、コンテキストの大きさから想像するより安く済みます。キャッシュの寿命を過ぎた古いセッションの再開時が最も高くつきます。

ほかに、画像がたまって Claude Code が古い画像を削除したとき、Claude Code のアップグレード後の最初の会話も切れます。自動更新は次回起動時に適用され、セッション途中には適用されません。

出典: How Claude Code uses prompt caching

切れない操作:CLAUDE.md 編集・権限モード・/rewind など

次の操作は会話の末尾に追記されるか、リクエストに触れないため、キャッシュが保たれます。

• ファイル編集:変更を知らせる <system-reminder> が追記され、必要なら Claude が再読み込みします。
• CLAUDE.md の編集:セッション開始時に1回読まれるため、途中で編集してもキャッシュは切れませんが、反映もされません。新しい内容は次の /clear、/compact、再起動で読み込まれます。
• 権限モードの変更:ただし opusplan ではモデル切り替えになります。
• 出力スタイルの変更:次のメッセージから適用されます。v2.1.251 より前は /clear か新規セッションまで適用されませんでした。
• skill・コマンドの呼び出しと /recap:履歴を置き換えず追記されます。
• /rewind:以前のキャッシュエントリに当たります。公式ドキュメントは、abandon したい作業では /compact の代わりに使うよう書いています。
• サブエージェント:親のキャッシュには影響しませんが、最初のリクエストは親のキャッシュを読まず、自分用のキャッシュを作ります。

出典: How Claude Code uses prompt caching

キャッシュの寿命(TTL)と設定

キャッシュは無操作が続くと期限切れになり、ヒットするたびにタイマーがリセットされます。長く席を外した後の最初のターンは遅くなることがあります。TTL は5分と1時間の2種類で、1時間は長い休憩に強い一方、キャッシュ書き込みの料金が高くなります。

公式ドキュメントによると、TTL を自分で選ばない場合に1時間を要求するのは、Claude サブスクリプションでプランの含まれる利用量の範囲内にあるときだけです。API キー、クラウドプロバイダー、使用量クレジットでは、メインの会話も5分です。

メインの会話の TTL は promptCacheTtl 設定か CLAUDE_CODE_PROMPT_CACHE_TTL 環境変数で指定でき、値は 5m か 1h だけです。v2.1.242 以降が必要です。

キャッシュは実質的に1台のマシンと1つのディレクトリ単位で、ディレクトリが違うセッションは互いのキャッシュに当たりません。

出典: How Claude Code uses prompt caching

効き具合の確認と、社内で使うときの注意

API は応答ごとに cache_creation_input_tokens(キャッシュへの書き込み)と cache_read_input_tokens(キャッシュからの読み込み)を返します。読み込みが多ければうまく効いており、書き込みが毎ターン多いままなら、プレフィックスのどこかが変わり続けています。

セッション単位では /usage を実行します。メインの会話の最初の応答後に Prompt cache (main) の行が加わり、ヒット率、ミス数、キャッシュが今温かいかが分かります。この表示には v2.1.251 以降が必要です。組織全体では OpenTelemetry エクスポーターがユーザーとセッションごとのトークン数を報告します。

Amazon Bedrock などでは、キャッシュはクラウドプロバイダー側にあります。LLM ゲートウェイや独自の ANTHROPIC_BASE_URL 経由では、キャッシュが効くかはゲートウェイ次第です。cache_control マーカーを、成功を返しつつ削除するゲートウェイでは、会話履歴全体が毎ターン未キャッシュ入力として課金されます。

無効化は DISABLE_PROMPT_CACHING を 1 にします。公式ドキュメントはデバッグ用途に限り、通常は有効のままにするよう書いています。

出典: How Claude Code uses prompt caching

参考(執筆時点)

• How Claude Code uses prompt caching(公式ドキュメント)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。