Claude Platformのコストを削減する3つの実装レバー

Claude Platformのコスト削減で押さえる3つのレバー

Claude Platformを使うアプリケーションのコストは、性能を落とさなくても下げられる余地が残っていることが多いです。効くレバーは3つに絞れます。プロンプトキャッシュのヒット率を上げること、フロンティアモデルの足を引っ張る指示のアンチパターンを取り除くこと、タスクの難度に合わせてeffortを調整することです。

3つはClaude Codeに組み込まれたclaude-apiスキルのコマンド(/claude-api prompt-audit /claude-api cost-optimize /claude-api hillclimb)から実行できます。ここでは症状ごとにどのレバーが効くかを先に示します。hillclimbのtrain/test分割と探索手順は/claude-api hillclimbの解説にあります。

前提

claude-apiスキルはClaude Code上で動きます。コードがanthropicか@anthropic-ai/sdkをimportしていると自動で有効になり、明示的に呼ぶときは/claude-apiを入力します(自動読み込みの詳細はclaude-apiスキルの自動読み込み)。必要なClaude Codeのバージョンはコマンドごとに違い、prompt-auditがv2.1.221以降、cost-optimizeがv2.1.247以降、hillclimbがv2.1.259以降です。3つのコマンドのうち/claude-api hillclimbだけは、正解ラベル付きの評価データセットが無いと実行できません。prompt-auditとcost-optimizeはデータセット無しでも動きます。

症状から着手する先を選ぶ早見表です。

キャッシュヒット率が想定より低いとき

Claudeはリクエストを処理する前に、プロンプトを内部状態へ変換するprefillという処理を行います。これは入力処理の中で最もコストがかかる部分です。プロンプトキャッシュはこの内部状態(KVキャッシュ)を保存し、同じプレフィックスで始まるリクエストが来たときに再計算を省きます。キャッシュ読み込みの価格は通常入力の1/10が基本で、Claude Opus 5.5では5%、Claude Fable 5.1とMythos 5.1では2.5%まで下がります。

キャッシュを機能させる条件は3つあります。特定のモデルに紐づくこと、プレフィックス全体がバイト単位で一致する必要があること、そして有効期限(TTL)があることです。既定のTTLは5分で、書き込みは5分キャッシュで通常入力の1.25倍、1時間キャッシュでは2倍の価格になります。

キャッシュできる長さにも下限があります。Opus 5.5・Opus 5・Fable 5.1・Mythos 5.1・Sonnet 5.5などは512トークン、Sonnet 5は1,024トークン、Haiku 4.5は4,096トークンです。下限に満たないプロンプトはエラーにならず、単にキャッシュされません。cache_creation_input_tokensとcache_read_input_tokensがどちらも0なら、この下限に届いていない可能性があります。

ヒット率を崩しやすい典型的な原因は次のとおりです。

• 会話の途中でeffortやthinkingの設定を変える(プロンプト先頭にレンダリングされるため)。Fable 5.1・Mythos 5.1・Opus 5.5・Opus 5・Sonnet 5.5では、per-message effort(後述)で変えればキャッシュが壊れません
• システムプロンプトに動的な値を混ぜる。タイムスタンプやIDのような変わる値がプレフィックスに入っていると、呼び出しのたびにキャッシュが崩れます
• ツール定義の順序を変える。Messages APIはツール定義をプロンプトの先頭に固定順で並べるため、定義を少しでも変えるとキャッシュが崩れます
• 会話を分岐する。サブエージェントや分岐先が親のキャッシュを共有できるのは、プレフィックスがバイト単位で一致し、同じモデル・同じeffortの場合だけです
• TTLより長く動くサブエージェントや同期的なツール呼び出し。5分TTLはリクエスト開始時点から数えるため、結果が返る前に5分を超えると、通常より高い書き込み価格で再構築することになります
• 並列リクエスト。キャッシュエントリーは最初の応答が始まってから使えるようになるので、同じプレフィックスを同時に投げても全件が書き込みになります。最初の1件の応答を待ってから残りを送ります

1時間TTLの損益分岐は、書き込み回数で数えると単純です。5分キャッシュは使われるたびに追加料金なしで延長されます。5分より空くが1時間以内には次の呼び出しが来るパターンで、5分キャッシュを2回書き直すと通常入力の2.5倍分(1.25倍×2)です。1時間キャッシュなら1回の書き込みで2倍に収まります。

Batch APIで共通プレフィックスを使い回すときは、先に1件だけ1時間キャッシュで書き込んでおき、その完了後に残りを投げる手順が使えます。バッチは完了まで5分から1時間かかることが多く、5分TTLでは途中で切れやすいためです。

自動化する手段として、リクエストの最上位にcache_controlを1つ置くだけの自動キャッシュがあります。ブレークポイントを最後にキャッシュ可能なブロックへ自動的に移動させるため、会話が伸びてもcache_controlを手で更新する必要がありません。明示的なブレークポイントを1つだけ置く場合は、前回の書き込み位置から20ブロック以上離れるとヒットしなくなります。このブロック数では、連続するtool_useブロックは1つ、連続するtool_resultブロックも1つの位置として数えます。多ターン会話での挙動やmax_tokens: 0を使った事前ウォームアップは、それぞれの記事で解説しています。基本の仕組みはPrompt Cachingの解説記事にあります。

Claude Codeのセッションで見るヒット率

Claude Codeの/usageにはSessionブロックがあり、キャッシュの状況も出ます。v2.1.251以降は、最初の応答のあとにPrompt cache (main)行が加わります。リクエスト数・入力トークンのうちキャッシュから返った割合・ミス回数・今キャッシュが温まっているかが1行に並びます。コスト関連のドキュメントに載っている出力例は次のとおりです。

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)

直近のミスに心当たりの原因があれば、likely cause: tool definitions changedのように行に併記されます(v2.1.260以降)。この行が数えるのはメインの会話だけで、サブエージェントは含みません。

TTLはClaude Code側でも切り替えられます。CLAUDE_CODE_PROMPT_CACHE_TTLでメインの会話、CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTLでサブエージェントやワークフローの要求を、5mか1hで指定します(v2.1.242以降)。APIキー利用の既定は5分で、1時間キャッシュの書き込みは高い単価で課金されます。

export CLAUDE_CODE_PROMPT_CACHE_TTL=1h
export CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m

FORCE_PROMPT_CACHING_5M=1を設定すると、上の指定より優先して5分に固定されます。

モデルを移行してもコストが下がらないとき

プロンプトには、過去のモデルの弱点を埋めるための指示が蓄積しがちです。こうした指示はフロンティアモデルの能力に対して古くなり、コストを押し上げる原因になります。アンチパターンは次の6種類です。/claude-api prompt-auditコマンド自体の詳しい使い方はClaude Codeのprompt-auditで古いモデル向けの記述を検出するで扱っています。ここでは効果の規模と読み方を示します。

/claude-api prompt-auditは、これらを作業ディレクトリ内のプロンプト・スキル・ツール説明(CLAUDE.mdやClaude Code自体の設定を含む)から検出します。

効果の数字は、実験の作りを知ったうえで読む必要があります。カスタマーサポート用のベンチマークで、きれいなプロンプトにアンチパターンを1つずつ意図的に混ぜ、6種類の旧式プロンプトを作りました。廃止済みのthinking設定・矛盾する返金ルール・手動のスクラッチパッド・「verify twice」・「be maximally thorough」・6段階の必須手順です。これをOpus 4.8、モデルIDだけ変えたOpus 5.5、prompt-audit適用後のOpus 5.5で走らせ、6本の平均を比べています。

結果は次のとおりです。

• Opus 4.8からOpus 5.5への切り替えだけで、コストは約18%減りました。Opus 5.5の入力トークンとキャッシュ読み込みが安いためで、プロンプトの手入れによる効果ではありません
• prompt-auditの適用で、コストはさらに約9%減り、正解率はおよそ2ポイント上がりました
• 「verify twice」は返金のたびに注文照会を二重に走らせ、「be maximally thorough」は数十回の不要なナレッジベース検索に化けていました

正解率が上がった原因は3つあります。廃止済みのthinking設定が、ルーティングのリクエストをAPIに丸ごと拒否させていました。矛盾する返金ルールのせいで、Opus 5.5は本来払うべき返金4件を顧客への確認待ちのまま保留していました。手動のスクラッチパッドは内蔵thinkingと衝突し、3件のチケットでツール呼び出しを実行せず思考内に書いて終わらせていました。

つまり、約9%という数字の大きさは、自分のプロンプトに混ざっているアンチパターンの数で決まります。きれいなプロンプトなら、削減の中心はモデルの単価差だけです。

/claude-api prompt-audit

Opus 5.5への移行にあわせてプロンプトを見直す作業は、thinking無効プロンプトの移行手順とあわせて進めると重複が少なくなります。

effortを上げても成績が伸びないとき

effortはClaudeに「どれだけ粘るか」を指示するパラメータです。低いeffortでは早く結論に達し、高いeffortでは検証や別解の検討を重ねます。同じモデルでも、effortを上げたときのコストと性能の伸び方は一様ではありません。

effortの誤設定は両方向で起こります。「高いほど良い」という思い込みは過剰な検討を招き、コストと遅延を増やしたうえで回答の質を下げることがあります。逆にeffortを下げすぎると、Claudeは十分な根拠が集まる前に止まります。ツール呼び出しの回数が減り、最初の検索結果だけで答えてしまうことがあります。

有効な調整方法として、まず強いモデルを低effortで試すことが挙げられます。CursorBench 3.2では、Claude Fable 5.1を低effortで動かすと、Fable 5を高effortで動かした場合と同等の性能を約3分の1のコストで達成しました。理由は2つあります。低effortでは1タスクあたりの作業量が減ること、そしてFable 5.1のキャッシュ読み込み単価がFable 5の1/4($0.25/MTok対$1.00/MTok)であることです。Fable 5の単価に揃えて比べても、Fable 5.1の低effortは約40%安くなります。

effortを途中で切り替えたいときは、per-message effortに対応したモデルならrole: "system"のメッセージでeffortの変更を渡すと、キャッシュ済みプレフィックスが保たれます。ベータ機能で、ベータヘッダmid-conversation-output-config-2026-07-01が必要です。contentは空にし、新しい値は次のuserターンから有効になります。Sonnet 5.5でも、thinking: {"type": "between_tools"}を指定しているときは、per-message effortでの変更は400エラーになります。未対応のモデル(Fable 5など)は、output_config.effort requires a model that supports per-turn effortという400エラーを返します。手順は会話の途中でeffortを切り替える実装で解説しています。

タスクの性質を理解することも重要です。effortを段階的に上げてもコストとスコアの曲線が平坦なら、そのタスクは思考量に律速されていないという判断材料になります。ただし評価が満点に張り付いていると平坦に見えるだけなので、飽和していない評価で測ります。

この探索を自動化するのが/claude-api hillclimbです。評価データセットを訓練用とテスト用に分割し、設定変更を提案し、失敗した訓練事例を読んで修正案を出します。

カスタマーサポートのベンチマークで走らせた例は、次の経過をたどりました。

1. 出発点はOpus 4.8の既定(高effort)です
2. Opus 5を低effortにし、prompt-auditの指摘(必須ツール呼び出しの儀式化・スクラッチパッド・矛盾ルール)を取り除くと、訓練正解率98.9%・1件2.6セントになりました
3. Sonnet 5・低effortへ切り替えるとコストは1件1セントまで下がりましたが、正解率は88.9%に落ちました
4. 失敗した訓練チケットを読んでルーティングルールと返金上限の参照を足し、98.9%まで戻しました

探索の中で一度も見せなかったホールドアウトの14件では、最終設定が90.5%(元の設定は78.6%)を約5分の1のコストで達成しました。訓練正解率の98.9%とは差があり、最終設定の性能は未見のデータで測った値のほうを見ます。

支出の内訳から洗い出すとき

個別のレバーを組み合わせて棚卸しするコマンドが/claude-api cost-optimizeです。まず支出の内訳を、Claude Admin APIキーがあれば組織の利用状況・コストレポートから、なければ各APIレスポンスのusageオブジェクトのログから、それも無ければリクエスト構築コードを読んで見積もります。そのうえで、プロンプトキャッシュの適用余地、prompt-auditによる指示の削減、出力量の制限、まとめて実行できる作業のBatch API化の順に節約策をランク付けします。評価データセットを渡せば、effortとモデル選択の性能・コストのトレードオフも計算します。

/claude-api cost-optimize

4つの公開ベンチマークで、Opus 5.5を基準に実行した結果です。

SWE-bench Verifiedのようにキャッシュが既に効いている場合は、残る削減幅が小さくなります。cost-optimizeの実行手順は/claude-api cost-optimizeの解説記事にまとめています。

導入手順とよくあるつまずき

3つのコマンドが読み込むものと、返してくるものは次のとおりです。

つまずきやすい点は次のとおりです。

• per-message effortを使わずにeffortの値を直接変えると、メッセージブロックのキャッシュが無効になります。ツール定義とシステムプロンプトへの影響はモデルごとに違います
• defer_loadingしたツールは、Claudeがツール検索で参照するまで会話に追加されず、その間は呼び出せません。よく使うツールを対象に含めていないか見直します
• 廃止済みの設定(手動thinking budgetなど)はエラーで弾かれます。prompt-auditを走らせる前に、モデル移行そのものが失敗していないかを先に調べます
• CIなどで非対話に実行するClaude Codeには、支出の上限をかけられます。v2.1.287のclaude --helpでは、--max-budget-usdは--printのときだけ効くと説明されています

まとめ

削減幅は、プロンプトに残る旧式の指示の数と、キャッシュが未適用だった分で決まります。モデルの単価差による削減とは分けて測ると、どのレバーが効いたかが見えます。