AIコーディングのPrompt Cacheが効かない原因とprompt-cache-skillsでの直し方

Claude CodeやClineの月額API料金が、本来より30%〜50%高くなっているかもしれません。利用量が多いのではなく、Prompt Cacheが機能していない可能性があります。

多くのAIコーディングAgentはprompt cachingを初期設定で有効にしますが、設定の小さな変更だけでキャッシュ対象のプレフィックス全体が無効になります。システムプロンプトにタイムスタンプを入れる、cache keyの計算を誤る、キャッシュスイッチを有効にしていない、TTLが短すぎる、といった問題です。エラーは出ず、請求明細にも原因は表示されないため、APIコストだけが高い状態になります。

prompt-cache-skillsは、こうした「気づきにくい失敗」を修正するdrop-in形式のskillライブラリです。条件が合えば、ほぼ0%だったキャッシュヒット率を80%以上に改善できる場合があります。ここからは課金の仕組み、4つの主な失敗原因、代表的な修正例、検証方法を順に見ていきます。

Prompt Cacheでコストが下がる仕組み

仕組みは単純です。安定したプレフィックスをキャッシュし、再利用時は通常の入力tokenより低い料金で処理します。

APIプロバイダーによって課金フィールド名は異なりますが、原理は共通しています。

課金タイプ	課金の特徴	適した場面	主なプロバイダー
cache_creation_input_tokens	初回にキャッシュを作成し、通常のtokenより高くなる場合がある	長いプレフィックスの初回リクエスト	Anthropic
cache_read_input_tokens	キャッシュヒット時は通常の入力tokenより大幅に安く、目安は約10%	安定したプレフィックスの反復利用	Anthropic
通常の入力token	通常料金で課金される	短いリクエスト、または頻繁に変わるプレフィックス	すべてのプロバイダー
cached_tokens（OpenAI）	キャッシュヒット時の料金が約50%下がる	安定したプレフィックスの反復利用	OpenAI
cached content（Gemini）	キャッシュの保存時間に応じて課金される	長いコンテキストを扱う場面	Google Gemini

Anthropicを例にします。システムプロンプトが2,000 tokenあり、同じAgentで1日に100回再利用するとします。キャッシュがヒットすれば、その2,000 tokenはcache_readとして課金され、通常の入力tokenの約10%になります。この部分の入力コストは約90%削減できます。

ただし、プレフィックスが安定し、繰り返し使われることが前提です。システムプロンプトにタイムスタンプやランダムIDが含まれ、リクエストごとに変わると、毎回プレフィックスを作り直します。cache_creationの繰り返しが通常の入力より高くなる場合もあります。

Agentのキャッシュが外れ続ける理由

次の問題はエラーにならないことがあります。請求額は見えても、無駄なコストの発生源が分かりません。

1. 変動メッセージがプレフィックスを壊します。システムプロンプトのプレフィックスにタイムスタンプ、ランダムID、その他リクエストごとに変わる値が含まれると、キャッシュ対象全体が無効になります。最も多い原因です。

2. Cache keyがない、または誤っています。一部のAgentツールはキャッシュ用のマーカーを正しく設定していないか、独自cache keyの計算を誤っています。プレフィックスが安定していても、API側が再利用可能なキャッシュとして認識できません。

3. キャッシュが初期設定で無効です。一部のAgentツールではprompt cachingを設定ファイルで明示的に有効にする必要があります。Agentが自動で処理すると思っていても、すべて通常の入力tokenとして課金されます。

4. TTLが短すぎます。たとえば有効期間が1時間なのに、実際のリクエスト間隔がそれを超える場合、次のリクエスト時にはすでにキャッシュが失効しています。

症状はAgentごとに異なります。prompt-cache-skillsのREADMEにはツール別の症状が整理されています。思い当たる原因があれば、まずリポジトリ内のSKILL.mdが現在のツールに合うかを確認してください。

prompt-cache-skillsとは

prompt-cache-skillsは、AIコーディングAgentが自分で読み、適用できるdrop-in形式のskill集です。

項目	内容
位置付け	AIコーディングAgentが読み取って適用できるdrop-in形式の修正skill
目標	条件が合う場合に、壊れた、または一部しか機能していないキャッシュのヒット率を80%〜99%に高める
対象Agent	Claude Code、Codex、Cline、Cursor、Devin、Gemini CLI、OpenCode、Aider、Continue、Roo Codeなど
リポジトリ	https://github.com/OnlyTerp/prompt-cache-skills
使い方	リポジトリをAgentに示す → 対応skillを適用させる → ヒットを検証する、またはskills/のpatchを手動で適用する
時間面の利点	各APIのキャッシュ仕様を一から調べる手間を減らせる

現在のstar数は約99です。skillsの一覧や名前は変わる可能性があるため、最新情報はリポジトリのREADMEで確認してください。

すべてを手動で調べる場合、各社のprompt cachingドキュメントを読み、Agentごとの設定差を比較し、どのフィールドがプレフィックスを壊しているかを推測する必要があります。このライブラリでは、各skillが具体的な失敗原因を特定し、対応するdiffと検証方法を提供します。

prompt-cache-skillsでAgentを修正する方法

Agentに自動修正させる方法と、skills/ディレクトリに沿って手動で変更する方法があります。

方法1：Agentに自動修正させる（推奨）

最初にリポジトリを指定します。次の指示をAIコーディングAgentに送ります。

https://github.com/OnlyTerp/prompt-cache-skills を読み、現在使用しているharnessに合うskills/内のskillをすべて適用してください。対象を確認 → diffを反映 → SKILL.mdに従って検証、の順で進めてください

次にAgentは、Cline、Continue、Aiderなど現在使っているツールを特定し、該当するskillを一覧にします。それぞれがどの失敗原因を修正するかを確認できます。

続いてdiffをレビューします。各skillディレクトリのSKILL.mdには、変更対象と具体的な修正内容が記載されています。内容を読み、現在の環境に適用して安全かを確認してください。

確認できたら変更を適用します。Agentにdiffを反映させ、ローカルまたはプロジェクトの設定ファイルを変更します。変更前に元の設定をバックアップしてください。

最後にヒットを検証します。tools/check_cache.pyでキャッシュが機能するかを確認します。具体的な手順は後述の「キャッシュが実際にヒットしたかを確認する方法」で説明します。

方法2：手動で修正する

Agentに設定を自動変更させたくない場合は、手動で適用できます。

最初にリポジトリを開きます：https://github.com/OnlyTerp/prompt-cache-skills

次にskills/ディレクトリを開き、使用しているツールに対応するskillを探します。たとえばcline-fix-volatile-msgやcontinue-enable-defaultsです。

続いてSKILL.mdを読みます。各skillには対象、症状、修正点、検証方法が記載されています。

説明に従って設定ファイルを手動で変更します。

最後にtools/check_cache.pyでキャッシュヒットを検証します。

安全上の注意

Agentにdiffを自動適用させると、ローカルまたはプロジェクトの設定が直接変更されます。SKILL.mdを読み、各変更点を理解してから承認してください。変更前に元の設定ファイルをバックアップします。

skillライブラリの代表的な修正例

リポジトリ内の各skillは、対象Agent、症状、修正diff、検証方法をまとめた完全な修正単位です。代表例を示します。

skill名	対象Agent	症状	修正点
cline-fix-volatile-msg	Cline	システムプロンプトのプレフィックスにタイムスタンプが入り、リクエストごとに変わる	変動メッセージを削除または固定する
cline-openai-cache-key	Cline + OpenAI	OpenAIのcache key計算が誤っている	cache key生成ロジックを修正する
cline-pin-timestamp	Cline	タイムスタンプがキャッシュを無効にする	タイムスタンプを固定または削除する
continue-fix-volatile-msg	Continue	システムプロンプトに変動フィールドが含まれる	変動メッセージを取り除く
continue-enable-defaults	Continue	prompt cachingが初期設定で無効になっている	キャッシュ設定を有効にする
continue-gemini-explicit	Continue + Gemini	Geminiのキャッシュ設定がない	キャッシュパラメーターを明示的に設定する
aider-1h-ttl	Aider	キャッシュTTLが1時間しかなく、頻繁に失効する	TTLを延ばすか、リクエスト頻度を調整する
aider-cache-default-on	Aider	キャッシュが初期設定で無効になっている	初期キャッシュスイッチを有効にする
opencode-detect-openai-compat	OpenCode	OpenAI互換モードでキャッシュが機能しない	OpenAI互換APIを検出して正しく処理する
opencode-bedrock-doc-blocks	OpenCode + Bedrock	Bedrockのドキュメントブロックでキャッシュに問題が起きる	ドキュメントブロックのキャッシュ戦略を修正する

skillは追加され続けており、名前も変わる可能性があります。READMEとskills/ディレクトリの最新状態を確認してください。利用中のAgentが一覧にない場合は、既存skillのSKILL.mdとpatchを参考に、似たキャッシュ問題を手動で調べられます。

キャッシュが実際にヒットしたかを確認する方法

prompt-cache-skillsには検証ツールtools/check_cache.pyがあります。コールド／ウォームの2回のリクエストを比較し、キャッシュヒット率を計算します。

確認手順

最初にcheck_cache.pyを次の場所から取得します。
https://github.com/OnlyTerp/prompt-cache-skills/blob/main/tools/check_cache.py

次にAPI認証情報を環境変数に設定します。

• Anthropic: ANTHROPIC_API_KEY
• OpenAI: OPENAI_API_KEY
• Google Gemini: GOOGLE_API_KEY

3番目にコールドリクエストを実行します。

python check_cache.py --provider anthropic --prompt "システムプロンプト" --message "ユーザーメッセージ"

cache_creation_input_tokensフィールドを確認します。

• 値があればキャッシュが作成されています
• input_tokensの値を記録します

4番目に1秒待ち、完全に同じpromptとmessageでウォームリクエストを実行します。

次のフィールドを確認します。

• cache_read_input_tokens：0より大きければキャッシュヒットです
• cache_creation_input_tokens：0またはフィールド自体がない状態になります
• input_tokens：キャッシュ分が通常課金から外れるため、大きく減るはずです

5番目にヒット率を計算します。

ヒット率 = cache_read_input_tokens / (cache_read_input_tokens + input_tokens)

例：

• 初回リクエスト：input_tokens=2000、cache_creation_input_tokens=1800
• 2回目のリクエスト：cache_read_input_tokens=1800、input_tokens=200
• ヒット率 = 1800 / (1800 + 200) = 90%

6番目にキャッシュが機能したかを判断します。

• キャッシュ有効：ウォームリクエストのcache_read_input_tokens > 0
• キャッシュ無効：ウォームリクエストのcache_read_input_tokens = 0、またはフィールドがない

指標の説明

• cache_creation_input_tokens：Anthropicでキャッシュ作成に使われたtoken数
• cache_read_input_tokens：Anthropicでキャッシュから読み取られたtoken数
• cached_tokens：OpenAIでキャッシュされた入力token数
• input_tokens：キャッシュされていない通常の入力token

ウォームリクエストでもcache_read_input_tokens = 0なら、前述の4つの原因に戻り、変動メッセージ、cache keyの誤り、初期設定の無効化、短すぎるTTLを確認してください。

このskillを使う場面と使わない場面

このライブラリは既知のキャッシュ障害を修正しますが、すべての処理に適しているわけではありません。

場面	推奨度	理由
長いシステムプロンプト + 類似リクエストの反復	推奨	安定したプレフィックスを再利用でき、キャッシュの効果が大きい
Claude CodeやClineなどのAgentコーディングツール	推奨	これらのツールを対象にしたプロジェクトである
月額請求が50ドルを超える	推奨	削減できる金額が大きく、調査に時間をかける価値がある
prompt cachingを設定済みだが、動作しているか不明	推奨	検証ツールで実際の動作を確認できる
短いプロンプト + 1回のリクエスト	非推奨	キャッシュのオーバーヘッドが効果を上回る場合がある
リアルタイムデータなどでシステムプロンプトが頻繁に変わる	非推奨	プレフィックスが安定せず再利用できない
1日に数回だけなど、リクエスト間隔がTTLを超える	要検討	再利用前にキャッシュが失効する可能性がある
対応一覧にないAgentを使っている	要検討	手動の適応または今後のコミュニティskillが必要になる

月額請求がすでに50ドルを超え、対応一覧のAgentを使っているなら、調査の効果は分かりやすいでしょう。リクエスト頻度が低い、またはプレフィックスが頻繁に変わる場合は、設定を変更する前に再利用回数を見積もってください。

リスクと注意点

適用前に次のリスクを確認してください。

1. 比較的新しいプロジェクトです。現在のstar数は約99で、skillsの一覧や名前は変わる可能性があります。最新情報はリポジトリのREADMEで確認してください。

2. 設定の自動変更には注意が必要です。Agentにdiffを適用させると、ローカルまたはプロジェクトの設定ファイルが変更されます。SKILL.mdを読み、各変更が現在の環境に必要かを判断してください。

3. 課金フィールドはプロバイダーごとに異なります。Anthropicはcache_creation/cache_read、OpenAIはcached_tokens、Geminiはcached contentを使います。正確なフィールド名と料金は各社の最新ドキュメントを確認してください。

4. キャッシュは万能ではありません。単発の短い呼び出しや、プレフィックスが頻繁に変わる処理では、ほとんど効果がないか、逆に高くなる場合があります。すべての場面でキャッシュを強制しないでください。

5. 検証ツールには限界があります。check_cache.pyは主にAnthropic API向けに作られています。OpenAIとGeminiのキャッシュ検証は、それぞれの公式ドキュメントも確認してください。

6. ヒット率は保証されません。「80%〜99%」はプロジェクトが示す目標です。実際のヒット率はプレフィックスの長さ、リクエスト頻度、TTLなどに左右されます。

次に読む記事

AIコーディングのコストをさらに下げたい場合は、次の記事も参考になります。

• AI Gatewayで監視、キャッシュ、フェイルオーバーをまとめる — 複数のプロバイダーを一元管理し、監視とコスト削減を進める方法

• AIの出力品質を高めるPrompt Engineeringの実践テクニック — promptを改善し、不要なtoken消費を減らす方法

• Computer-Use Agent：AIにPCを操作させる — コンピューター操作Agentの仕組みを理解し、作業フローを改善する方法

公式リソース：

• prompt-cache-skills GitHubリポジトリ
• Anthropic Prompt Cachingドキュメント
• OpenAI Prompt Cachingドキュメント
• Google Gemini Context Cachingドキュメント