Claude Codeの長いタスクでは、Prompt Cacheの命中率がコストと速度に直接影響する。キャッシュでTokenを節約できることは知られているが、どの操作で突然キャッシュが外れるのかは見落とされがちだ。
毎回のリクエストは、左から右へ流れるコンテキストの鎖として考えるとわかりやすい。
|
|
左にある内容ほど安定させるべきで、キャッシュ効果も大きい。左側が変わると、その後ろのキャッシュも再計算されやすい。逆に右側の変化は影響範囲が小さい。
つまりClaude CodeのPrompt Cache最適化は、勘ではない。タスク開始前にモデル、MCP、Skills、CLAUDE.mdなどの基本コンテキストを準備し、開始後はできるだけ変えないことが重要だ。
Prompt Cacheは文字列そのものをキャッシュしない
Prompt Cacheは、プロンプト文字列をそのまま保存するだけの仕組みではない。Transformerモデルでは、前方のコンテキストを注意層で計算したKey/Value状態、つまりKV cacheが重要になる。
これは2つのことを意味する。
- 前方のコンテキストが安定していれば、後続リクエストで一部の計算結果を再利用できる。
- モデル、ツール定義、システムプロンプト、前方メッセージが変わると、以前のキャッシュを再利用できないことがある。
Anthropic公式ドキュメントも、失効階層を tools -> system -> messages と整理している。ツール定義の変更は全体のキャッシュに影響し、system層の変更はsystemとmessagesに影響し、messages層の変更は主にメッセージキャッシュに影響する。
Claude Codeではさらに CLAUDE.md、Skills、MCP、プラグイン、subagentなどが関わるため、実際の利用ではキャッシュ失効点を踏みやすい。
キャッシュを壊す要因1：途中でモデルを切り替える
モデル切り替えは最も影響が大きい操作の一つだ。
Prompt Cacheはモデルごとに分離される。Opus、Sonnet、Haikuは構造や重みが異なるため、同じテキストから計算したKV cacheも共有できない。Opusで長いコンテキストを作ったあとSonnetへ切り替えても、SonnetはOpusのキャッシュを再利用できない。
そのため、節約のつもりで途中から安いモデルへ切り替えると、かえってそれまでのキャッシュが無駄になることがある。本来cache read価格で読めたコンテキストが、再度書き込みと計算の対象になる。
安定したやり方は次の通り。
- メイン会話ではモデルを固定する。
- 安いモデルで処理したい支線タスクはsubagentに分離する。
- 支線エージェントに検索、探索、整理を任せ、要約だけをメイン会話へ戻す。
こうするとメインの長いコンテキストを動かさず、キャッシュ命中率を保ちやすい。
キャッシュを壊す要因2：途中でMCPを追加する、プラグインを再読み込みする
MCPはClaude Codeへツールを提供する。新しいMCPサーバーを追加するとツール一覧が変わる。ツール定義はコンテキスト鎖の最も左側にある。
Prompt Cacheの視点では、ツール一覧が変わると、その後ろのsystemとmessagesも再計算が必要になりやすい。MCPが多い場合、ツール定義そのものが多くのTokenを占めるため、失効コストは大きくなる。
ただし重要な細部がある。Claude Codeは通常、セッション起動時にMCP設定を読む。途中で設定を変えても現在のsessionにすぐ影響するとは限らない。本当に注意すべきなのは、再起動、resume、プラグイン再読み込み、ツール一覧の再構築が起きる場面だ。
おすすめは：
- 長いタスクの前に必要なMCPをまとめて用意する。
- 作業中に不足に気づいてインストールし、再読み込みする流れを避ける。
- 大きなMCPツールセットは必要時だけ使う、またはデフォルト有効数を減らす。
- ほとんど使わないMCPを常時有効にしない。
ツール定義が安定していてこそ、Prompt Cacheは安定して命中する。
キャッシュを壊す要因3：途中でCLAUDE.mdを編集する
CLAUDE.mdはClaude Codeのプロジェクト記憶ファイルだ。ビルドコマンド、テストコマンド、設計上の約束、コードスタイル、プロジェクト固有の注意点を書くのに向いている。
便利だが、これもコンテキストに入る。Claudeのヘルプでは、CLAUDE.mdはセッション開始時に読まれ、ユーザーメッセージとしてClaudeへ渡されると説明されている。またAnthropicのPrompt Cacheも使われる。最初のリクエストでは通常の入力価格を払い、以後キャッシュが有効なら低いcache readコストで処理される。
問題は、CLAUDE.mdが内容で識別されることだ。ファイル内容を変えると、旧キャッシュとは一致しない。
そのため、長いタスクの途中で頻繁にCLAUDE.mdを編集しないほうがよい。より良い使い方は：
- タスク開始前に
CLAUDE.mdが十分か確認する。 - 安定したルールはファイルへ、臨時指示は現在の会話へ置く。
- 一度だけの要望のために長期記憶ファイルを編集しない。
- どうしても変更するなら、次の段階を新しいsessionや新しいフェーズとして扱う。
CLAUDE.mdは安定したプロジェクト説明であり、毎回変えるメモ帳ではない。
キャッシュを壊す要因4：途中でSkillsをインストールまたは更新する
Skillsもコンテキストの一部だ。新しいSkillを入れる、Skillを更新する、Skill一覧が変わると、セッションへ注入されるコンテキストも変わる。
こうした変化は、reload、resume、新しいsessionで反映されることが多い。messagesが再構築されると、古いキャッシュは命中しにくくなる。
MCPと同じく、次のように扱うとよい。
- タスク開始前に必要なSkillsを決める。
- 同じ種類のタスクではSkillセットを固定する。
- 長いタスクの途中でSkillsを追加しない。
- 新しいSkillを入れたら、新しい段階の始まりとして扱う。
コンテンツ作成、レビュー、デプロイ、翻訳など反復する作業では、よく使うSkillsを固定するとコンテキスト構造が安定する。
キャッシュを壊す要因5：TTLを超えてアイドルになる
Prompt Cacheは永久に保存されない。一般的なデフォルト有効期間は数分程度で、Claude Code関連の説明でも約5分のキャッシュウィンドウが言及されることがある。TTLを過ぎると、同じリクエストでもサーバー側でキャッシュが消えている可能性がある。
長いタスクで「さっきまで安かったのに、少し離席したらTokenが増えた」と感じる原因はこれだ。
Claude Codeの出力を読む、ファイルを確認する、テストを走らせる、次の手を考える。こうした作業だけで5分はすぐ過ぎる。
環境が対応しているなら、長いタスクの前に1時間のPrompt Cache TTLを有効化できる。
|
|
Windows PowerShellでは：
|
|
1時間キャッシュの書き込みコストは、通常5分キャッシュより高くなる。短いタスクには向かないこともあるが、大規模コードベース、長い会話、複雑な多段階開発では、頻繁にキャッシュが切れるより安くなる場合がある。
Tokenを節約しやすいClaude Code長タスクの組み方
安定した流れはこうだ。
- タスク開始前にモデルを決め、頻繁に切り替えない。
- 必要なMCPを有効にし、不要なMCPは切る。
CLAUDE.mdは短く、安定した、長期的に有効なルールに絞る。- 今回必要なSkillsを事前に準備する。
- 複雑なタスクでは1時間TTLを検討する。
- 大きなタスクは段階に分けるが、各段階の内部ではコンテキスト構造を安定させる。
- 支線探索はsubagentや別sessionで行い、メイン会話を汚さない。
目的はすべてのキャッシュミスをなくすことではない。見落としやすく、コストの高い失効を避けることだ。
簡単な判断基準
次の一文で判断できる。
この操作はモデル、ツール定義、システムコンテキスト、またはセッション冒頭の固定メッセージを変えるか？
答えがはいなら、Prompt Cacheに影響する可能性が高い。コンテキスト鎖の左側に近いほど影響は大きい。
よくある操作はこう整理できる。
- モデル切り替え：高リスク。モデルごとにキャッシュが分離される。
- MCP追加またはプラグイン再読み込み：高リスク。ツール一覧が変わる。
CLAUDE.md編集：中高リスク。プロジェクト記憶が変わる。- Skillsインストール：中高リスク。注入コンテキストが変わる。
- 通常の会話継続：低リスク。主にmessagesを追加するだけ。
- TTL超過のアイドル：高リスク。サーバー側キャッシュが期限切れになる。
まとめ
Claude CodeのPrompt Cache最適化で大事なのは、パラメータを暗記することではなく、sessionの前方コンテキストを安定させることだ。
モデルを気軽に切り替えない。MCPやSkillsを作業途中で増やさない。CLAUDE.mdを臨時メモとして頻繁に編集しない。複雑なタスクではTTL延長を検討する。これらを守るだけで、長いタスクのTokenコストと応答速度はかなり予測しやすくなる。
実用的な一言にすると、始める前に整え、始めた後はあまり動かさない。