背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

1. これは一言でいうと何か

プロンプトキャッシングは、Claude Code を速く・安くしている仕組みです。モデルはリクエスト間で何も記憶しないため、Claude Code は毎ターン完全なコンテキストを再送信しています。キャッシングがなければ、API はそのたびに全履歴を処理し直すことになります。

Claude Code はこれを自動で扱うので、普段は意識しなくて構いません。それでも仕組みを知る価値があるのは、キャッシュを無効にする操作が存在し、その直後のターンだけ遅く・高くなるからです。前回（第13回）がコンテキストに「何が入るか」の話だったのに対し、今回は「入ったものが再利用されるかどうか」の話です。

2. どういう場面で役立つか

• 特定のターンだけ突然遅くなったとき：原因はたいていキャッシュの再構築です。モデルを切り替えた、努力レベルを変えた、MCP サーバーが落ちて再接続した、といった心当たりを探せます。
• 設定を変えたのに効かないとき：CLAUDE.md や出力スタイルはセッション開始時に1回読まれてメモリに保持されます。セッション中の編集はキャッシュを壊さない代わりに、適用もされません。 一部の設定が再起動を待つ理由がここにあります。
• 使用量が想定より多いとき：後述の2つのトークン数を見れば、キャッシュが効いているかを判定できます。
• 長時間離席したあと：キャッシュは無操作時間で期限切れになります。戻ってきた最初のターンが遅いのは想定内です。

逆に、気にしなくてよいこと。 通常利用でキャッシングを無効にする理由はありません。無効化用の環境変数は用意されていますが、これは特定のモデルやプロバイダーで挙動をデバッグするためのもので、ドキュメントも「通常の使用では有効のままに」と明記しています。

3. キャッシュを壊す操作と保つ操作（元ページにコード例はありません）

前提：3つのレイヤーと「プリフィックス一致」

API はリクエストの先頭部分（プリフィックス）を、最近処理した内容と照合してキャッシュを効かせます。一致は完全一致です。したがってプリフィックスのどこか1か所でも変われば、それ以降がすべて再計算されます。ファイル単位・セグメント単位のキャッシュは存在しません。

Claude Code はこれを最大限使うため、変わりにくいものが先に来るようリクエストを並べています。

レイヤー	内容	変わるタイミング
システムプロンプト	コア命令、ツール定義、出力スタイル	ツール定義のセットが変わる / Claude Code のアップグレード
プロジェクトコンテキスト	CLAUDE.md、自動メモリ、スコープなしルール	セッション開始時、/clear や /compact の後
会話	メッセージ、応答、ツール結果	毎ターン

構造がそのまま結論になります。会話レイヤーへの追加はキャッシュを保つ。システムプロンプトへの変更はすべてを無効にする。 後者を変えると、それ以降の全コンテンツが別のプリフィックスの後ろに置かれてしまうためです。

もう2つ、プロンプト文には現れないがキャッシュキーになるものがあります。モデルと努力レベルです。どちらもセッション途中で変えると全体が再計算されます（努力レベルの変更時は、Claude Code が適用前に確認ダイアログを出します）。

キャッシュを壊す操作

モデルの切り替え、努力レベルの変更、高速モードの有効化、MCP サーバーの接続・切断、プラグインの有効・無効、ツール全体の拒否、会話のコンパクト化、Claude Code のアップグレード。

いくつか補足します。opusplan 設定を使っていると、Plan Mode の出入りがそのままモデル切り替えになります（Opus と Sonnet を行き来するため）。MCP は「ツール検索で遅延されているか」で結果が変わります。既定の遅延ツールなら接続・切断してもキャッシュは保たれ、alwaysLoad などでプリフィックスに載っている場合だけ無効化されます。しかもこの無効化は、stdio サーバーのプロセス終了や HTTP セッションの期限切れ、自動再接続であなたの操作なしに起こり得ます。

プラグインも同様で、スキル・コマンド・エージェント・フック・LSP・モニター・テーマは決してキャッシュを壊しません。例外は MCP サーバーを含むプラグインだけです。

アップグレード後のセッション再開には注意が要ります。 履歴が別のシステムプロンプトの後ろに置かれるため全履歴が再処理され、コストは会話の長さに比例します。長いセッションに戻る最初のターンが、そのセッションで最も高いリクエストになり得ます。

キャッシュを保つ操作

リポジトリ内のファイル編集、セッション中の CLAUDE.md 編集、出力スタイルの変更、権限モードの変更、スキルとコマンドの呼び出し、/recap、/rewind、サブエージェントの生成。

ここも理屈は一貫しています。スキルや Plan Mode の指示は会話メッセージとして後ろに追加されるので、既存のプリフィックスは無傷です。ファイル編集がキャッシュに影響しないのは、ファイル内容がコンテキストに入るのは Claude が読んだ瞬間だけで、過去の読み取り記録が遡って書き換わらないからです（変更は <system-reminder> で通知され、必要なら読み直されます）。

/recap と /rewind の位置づけも明快です。/recap は要約をコマンド出力として追加するだけなので、履歴を置き換える /compact と違いキャッシュが残ります。/rewind は以前のターンまで切り詰めるので、既にキャッシュ済みのプリフィックスに戻ることになります。

4. まとめと次回予告

• キャッシュはプリフィックスの完全一致で効きます。前方を変えると後ろが全部やり直しです。
• 壊すのは「システムプロンプト層を触る操作」。保つのは「会話の末尾に足す操作」。
• モデルと努力レベルはプロンプト文ではなくキャッシュキー。途中で変えると再計算されます。

実務でいちばん効く助言は1行です。モデルと努力レベルはセッションの最初に決め、/compact はタスクの切れ目に取っておく。 タスク中の変更が少ないほどキャッシュヒット率が上がります。捨てたい方向に進んでしまった場合は、/compact より /rewind が有利です。前者が新しいプリフィックスを作るのに対し、後者は既存のキャッシュへ戻るためです。

効いているかの確認方法も知っておくと便利です。API はすべての応答で2つの数値を返します。cache_creation_input_tokens（このターンで書き込まれた分。書き込みレートで課金）と cache_read_input_tokens（キャッシュから提供された分。**標準入力レートの約10%**で課金）です。読み取りに対して書き込みの比率が高いほど良く、毎ターン書き込みが高止まりしているなら、プリフィックスの何かが変わり続けています。

TTL（生存時間）は認証方法で変わります。 Claude サブスクリプションでは自動的に1時間の TTL が要求されます（使用量がプランに含まれるため追加費用がないからです）。ただしプランの上限を超えて使用クレジットを消費している間は、自動的に5分へ下がります。API キーやサードパーティ経由ではトークン課金のため既定は5分で、ENABLE_PROMPT_CACHING_1H=1 で1時間にオプトインできます。

最後に見落としやすい点を。キャッシュは実質的にマシンとディレクトリにスコープされます。 システムプロンプトに作業ディレクトリやプラットフォーム、自動メモリのパスが埋め込まれるためで、同じリポジトリの worktree どうしでもキャッシュは共有されません。サブエージェントも独自のキャッシュを持ち、サブスクリプションでも5分 TTL です。一方フォークは親のシステムプロンプト・ツール・履歴をそのまま引き継ぐため、最初のリクエストで親のキャッシュを読めます。

次回予告：連載の締めくくりとして「ベストプラクティス」を取り上げる予定です。

関連ページ（本記事で触れた概念の詳細）：何がコンテキストに入るか、圧縮後の残存 →「コンテキストウィンドウ」、/model と opusplan、努力レベル →「モデル設定」、ツール検索と alwaysLoad →「MCP」、拒否ルールの書き方 →「権限」、/rewind →「チェックポイント」、statusline での監視 →「ステータスライン」、API 側の仕組みと価格 →「プロンプトキャッシング（Claude API）」。

---

本記事は執筆時点の公式ドキュメント（Claude Code がプロンプトキャッシングを使用する方法）に基づきます。最新は公式ドキュメントをご確認ください。