Claude CodeでTokenを節約する：モデル、MCP、CLAUDE.md、Skillsがキャッシュに与える影響

Mon, 18 May 2026 18:30:24 +0800

Claude Codeの長いタスクでは、Prompt Cacheの命中率がコストと速度に直接影響する。キャッシュでTokenを節約できることは知られているが、どの操作で突然キャッシュが外れるのかは見落とされがちだ。

毎回のリクエストは、左から右へ流れるコンテキストの鎖として考えるとわかりやすい。

`1`	`tools -> system -> CLAUDE.md / skills -> messages`

左にある内容ほど安定させるべきで、キャッシュ効果も大きい。左側が変わると、その後ろのキャッシュも再計算されやすい。逆に右側の変化は影響範囲が小さい。

つまり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を有効化できる。

`1`	`export ENABLE_PROMPT_CACHING_1H=1`

Windows PowerShellでは：

`1`	`$env:ENABLE_PROMPT_CACHING_1H="1"`

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コストと応答速度はかなり予測しやすくなる。

実用的な一言にすると、始める前に整え、始めた後はあまり動かさない。

Token Optimization on KnightLiブログ