/claude-api cost-optimizeでAPIコストを段階的に削減する
Claude Codeの/claude-api cost-optimizeが、キャッシュ・トークン整理・batch・effort・モデル選定の5つのレバーを測定しながら1つずつ適用する仕組みをまとめます。
/claude-api cost-optimizeとは何か
/claude-api cost-optimizeは、既存のClaude API実装のコストを、出力品質を落とさずに削れる範囲から順に検証していくClaude Codeのコマンドです。Claude Code v2.1.247で追加された、バンドルスキルclaude-apiのサブコマンドの1つです。
呼び出すと、まずプロジェクトのスコープと品質基準を確認し、トークンの内訳を調べたうえで、キャッシュ・トークン整理・バッチ処理という品質を犠牲にしないレバーを先に検証します。それでも足りない場合だけ、effortとモデル選定という品質とコストを引き換えるレバーへ進みます。この順序自体が固定の設計です。
「無料」という言葉には注意が必要です。ここでいう無料レバーとは出力品質を犠牲にしないという意味で、コマンドの実行自体が無料になるわけではありません。ベースラインの計測やeffortの比較はモデルを実際に呼び出すため、実行前にユーザーの承認を求める設計になっています。bareで/claude-api cost-optimizeとだけ打った場合、変更はいきなり適用されず、提案(diff)として提示されます。
claude-apiスキル自体の自動起動条件やmigrate・prompt-auditなど他のサブコマンドとの役割分担はClaude Codeのclaude-apiスキルでAPI移行を自動化するで扱っています。
/claude-api cost-optimize実行前に確認する前提条件
3つの前提を先に固めておくと、後続のステップが迷いなく進みます。
スコープは、リクエストでファイルやディレクトリを指定していればそれが対象になり、指定がなければプロジェクト内のClaude API呼び出し全体が対象になります。対話的なパスとバッチジョブは別のトラフィッククラスとして扱い、コストはクラスごとに測定します。Anthropicの直接提供API(first-party API)・Claude Platform on AWS・Bedrock・Vertex・Foundryのどのプラットフォーム向けコードかも先に確認します。レバーごとに使える機能がプラットフォームで変わるためです。
品質基準は、プロジェクトのeval・テストスイート・成果物チェックの有無です。無ければその旨を報告に明記します。無料レバーは基準がなくても提案されますが、effortやモデル選定のようなトレードオフ系レバーは「evalが要る」という保留扱いになります。
ベースラインは、次の3つのうち得やすいものから採用します。
| データソース | 得られる粒度 | 制約 |
|---|---|---|
| Admin API(使用状況・コストレポート) | 得られる粒度実測のドル額(measured) | 制約sk-ant-admin01-から始まる専用キーが必要。個人アカウントでは発行できず、Claude Platform on AWSでは提供されない |
アプリ自身のresponse.usageログ | 得られる粒度実測に近い割合(% of bill) | 制約ログを取っていなければ、ログ追加そのものが無料レバーの1つになる |
| コードを読んだ見積もり | 得られる粒度相対的な大小(largest / medium / small) | 制約具体的な金額や割合は出ない |
Step 0〜1 — スコープと基準を決めてトークンの内訳を調べる
Step 0でスコープ・品質基準・ベースラインを確定したら、Step 1でトークンの内訳を調べます。Admin APIキーがある場合は、GET /v1/organizations/usage_report/messages(group_by[]=model)でモデル別の未キャッシュ入力・キャッシュ書き込み・キャッシュ読み取り・出力の4種類のトークン数を、GET /v1/organizations/cost_report(group_by[]=description)でドル建ての内訳を取得します。どちらもレポートを読むだけでトークンを消費しない呼び出しで、リクエスト完了から約5分でデータに反映されます。
Admin APIが使えない場合は、システムプロンプトとツールスキーマのサイズ、ループの深さ、画像やPDFの解像度、max_tokensの設定値などをコードから読み取って見積もります。アプリがすでにresponse.usageをログしているなら、それを先に確認するのが最優先です。キャッシュのヒット率・入出力比率が推測から実測に変わります。
得られたデータの粒度に応じて、各レバーの削減余地を3段階のどれかで表現します。Admin APIの実測データがあれば「ドル額」、アプリのログやユーザー申告の請求額があれば「請求額に対する割合」、コードの見積もりしかなければ「largest / medium / smallの相対バケット」です。同じトークンを別のレバーが二重に主張しないよう、上位のレバーで削れる分を差し引いてから順位付けします。
Step 2 — 無料レバーを先に適用する
自由に削れる分から順に検証します。それぞれの効果はAnthropicが公開したベンチマークの計測値で、ワークロードによって変動します。
| レバー | 測定された効果の目安 | 備考 |
|---|---|---|
| プロンプトキャッシュ | 測定された効果の目安エージェントループのコストが2.5〜3.7倍圧縮(ヒット率81〜90%)。小規模なトリアージエージェントでは単独で83%削減 | 備考常時オンのレバー。詳しい仕組みはPrompt Cachingを理解する、多ターン会話での挙動は自動プロンプトキャッシュは多ターン会話でどう動くかを参照 |
| トークン整理(入力・ループ・出力) | 測定された効果の目安ツール定義の遅延読み込みで502ツール構成でも実行コストが横ばい。テーブルをFiles APIへ逃がすと正答率6/25→25/25、コストは約1/12 | 備考古いモデル向けの記述を検出するprompt-auditもこの中のサブレバーとして実行される |
| バッチ処理 | 測定された効果の目安標準tierの全トークンが50%オフ(キャッシュの書き込み・読み取りにも適用) | 備考結果到着は最大24時間以内の非同期処理。Managed Agentsセッションには使えない |
入力・ループ・出力のトークン整理は3つの下位レバーに分かれます。入力側では、ツール定義が多いプロジェクトでtool searchのdefer_loadingを使うと、スキーマトークンが約1万トークンを超えたあたりから効果が出ます。大きな参照ドキュメントは丸ごと渡さずツールの背後に置き、必要な部分だけ取得させます。ループ側では、コンテキストエディティング(古いツール結果のクリア)はそれ自体が節約レバーではなく、コンテキストウィンドウを確保するための機能です。計測した実行では、コンテキストエディティングはむしろコストを増やす結果になりました。長いループを一定回数走らせた別の実行では、サーバー側のコンパクションが38%のコスト削減につながっています。出力側ではmax_tokensを「調整用のつまみ」ではなく「打ち切りの安全弁」として扱い、コーディング用途では64,000(xhigh・max effortでは128,000)を目安にします。
プロンプトオーディットは入力側トークン整理の一部として実行され、古いモデル向けに書かれた指示文を洗い出します。サポートデスク評価の実測では、Claude Opus 4.8向けのプロンプトをそのままClaude Opus 5で使うとチケットあたりのコストが36%増え、正確性の改善はありませんでした。オーディット後は同じ精度のまま14%安くなり、正答率も92%から97%に上がっています。プロンプトオーディット単体の検出パターンと実行手順は/claude-api prompt-auditで古いモデル向けの記述を検出するにまとめています。
Step 2(続き) — effortとモデル選定は最後に回す
トレードオフ系のレバーは、無料レバーを検証し終えたあとに順番を守って試します。先に品質を落とすレバーへ飛ぶと、無料レバーで削れたはずのコストまで一緒に犠牲にしてしまうためです。
effortの掃引は、モデルを変える前にまず試すレバーです。同じセッション内でeffortを切り替えるとキャッシュが無効化されて比較が歪むため、設定ごとに別セッションで実行します。ワークロードの性質によって効き方が大きく変わります。
| ワークロードの性質 | lowの効果 | mediumの効果 |
|---|---|---|
| リサーチ・ナレッジワーク | lowの効果正答率1〜3点減でコストは1/3〜半分 | mediumの効果デフォルトと同等の正答率でコストは70〜85% |
| 長時間コーディング(Claude Opus 5) | lowの効果正答率8点減でコストは1/4 | mediumの効果正答率2点減でコストは半分 |
チェッカーやテストで正誤判定できるワークロードでは、低いeffortで全件実行し、失敗した分だけデフォルトのeffortで再実行する運用も測定されています。コーディングの実測では、この方式で正答率約93%・タスクあたり約0.70ドルに対し、全件をデフォルトで実行すると正答率91.7%・約1.39ドルでした。同程度の正答率を半分のコストで得ています。
タスク予算はモデルにトークン予算を伝えて自分でペースを配分させる仕組みで、コーディングの実測では緩めの予算で正答率2.7点減・18%節約、最も厳しい予算で4.4点減・47%節約でした。予算は下限2万トークンを下回ると拒否され、タスクの最初のリクエストで一度だけ設定します(途中変更はキャッシュを無効化します)。
モデル選定は最後に回します。判断基準は「トークン単価」ではなく「完了したタスクあたりのコスト」です。コーディングの一部実測では、Claude Opus 5とClaude Fable 5が正答率91.7%対91.3%とほぼ並び、Claude Opus 5のコストはClaude Fable 5の約60%でした。一方でClaude Haiku 4.5は、知識質問への回答でClaude Opus 5の約1/10のコストながら正答率は63%対92%まで下がっており、長いエージェントループには不向きです。20問中2問が支出全体の43%を占めた実測例もあり、比較は平均値ではなく難しいタスクの尾側で行うのが安全です。モデルを下げる場合は1段階ずつ、そのたびにeffortを再掃引します。
処理を分担できるワークロードでは、安価なモデルが難しい判断だけ上位モデルに相談する「アドバイザー」構成、上位モデルが計画して下位モデルへ作業を配る「オーケストレーター」構成も選択肢です。オーケストレーターは1つのコンテキストウィンドウに収まらない規模の作業で、単独実行より55%安く済んだ実測がありますが、アドバイザー構成は効果がベンチマーク上でノイズの範囲に収まった例もあり、どちらも先に効果を測ってから採用するレバーです。
Step 3〜4 — 1レバーずつ測定してレポートにまとめる
採用が決まったレバーは、ランキング順ではなくStep 2で並んだ順(無料レバー→effort・予算→モデル選定)に1つずつ適用します。レバーごとに個別のdiffを作り、該当するトラフィッククラスのevalを再実行して、直前の構成と正答率・コストを比較します。コストは下がったのに正答率も下がった場合は、それは最適化ではなく差し戻しの対象です。
evalが無いプロジェクトでも、最小構成で作れます。本番から抜き出した(または手書きの)20〜30件程度の固定入力セットを用意し、正解との突き合わせ・簡単なルーブリック・自動チェッカーのいずれかで判定し、各設定を1回ずつ回して正答率とタスクあたりコストを記録します。最終的な切り替え判断には約50件・各設定5回以上の試行が推奨されていますが、レバーごとの採否判断はもっと小さいセットでも足ります。
Step 4の成果物 — レポートの構成
最終的な報告は2つの成果物にまとまります。
- コストプロファイルと計画: Step 0の前提(スコープ・品質基準・ベースライン)、Step 1のトークンプロファイル、採用したレバーとその根拠、見送ったレバーとその理由
- 変更そのもの: レバー1つにつきdiff1つ。承認を得て適用・測定済みのものと、承認待ちで提案のまま残っているものを区別する
削減の余地が小さいワークロードでは「変更なしを推奨」も正当な結論として扱われます。
よくあるつまずき
- evalが無いままトレードオフ系を試そうとする: 無料レバーはevalが無くても提案されますが、effort・予算・モデル選定はevalが無い間は提案止まりで、実際には適用されません
- コンテキストエディティングを節約レバーだと思い込む: 古いツール結果をクリアする機能はコンテキストウィンドウを確保するためのもので、計測した実行ではキャッシュを壊す分だけコストが増えました
- Admin APIキーが無いのに実測を前提にする: 個人アカウントでは発行できず、Claude Platform on AWSでも提供されません。無ければアプリの
response.usageログかコードの見積もりに切り替えます - effortを同一セッションで比較する: セッション内でeffortを切り替えるとキャッシュが無効化され、コスト比較の前提が崩れます。設定ごとに別セッションを使います
- バッチ処理をManaged Agentsセッションに使おうとする: バッチAPIはManaged Agentsセッションでは利用できません。対話的なセッションはバッチ化の対象外として切り分けます
まとめ
/claude-api cost-optimizeは、スコープと品質基準を固めてからトークンの内訳を調べ、キャッシュ・トークン整理・バッチ処理という品質を犠牲にしないレバーを先に検証し、それでも足りなければeffortとモデル選定のトレードオフへ進む、という順序が固定されたコマンドです。無料レバーでもコマンドの実行自体には実際のAPI呼び出しが伴い、ユーザーの承認を経てから走ります。同じclaude-apiスキルにあるPython SDKのメジャーバージョン移行コマンドは/claude-api upgradeでPython SDKをv0.xからv1へ移行するで扱っています。