Claude Code コスト最適化:25 項目チェックリスト

システムプロンプトに cache_control を有効化する

API を直接利用する場合、システムプロンプト(あるいはリクエスト間で繰り返される大きな文脈ブロック)を cache_control: {"type": "ephemeral"} ブロックで囲んでください。キャッシュ済みトークンの単価は未キャッシュ入力トークンの 10% です。10,000 トークンのシステムプロンプトを 1 日 50 回繰り返すなら、1 日あたり 450 万トークン分の節約となります。

system=[{
  "type": "text",
  "text": your_large_system_prompt,
  "cache_control": {"type": "ephemeral"}
}]

同じドキュメントを複数回問い合わせる前にキャッシュする

同一ドキュメント(コードベースの一部、仕様書、PDF)に対して複数のプロンプトを走らせるなら、初回リクエスト時にキャッシュしてください。以降のリクエストはキャッシュにヒットする限り、ドキュメント分を 10% で支払います。損益分岐点は 2 リクエスト、3 リクエスト以上で確実に元が取れます。

レスポンスヘッダからキャッシュヒット率を監視する

すべての API レスポンスから usage.cache_read_input_tokens を読み取ってください。システムプロンプトを多用するアプリケーションでヒット率が 60% を下回るなら、キャッシュは利用される前に失効しています。エフェメラルキャッシュは 5 分で消えるため、リクエストがその窓内に届くようにしてください。

キャッシュ対象はプロンプトの先頭に置く

キャッシュは内容と位置の両方をキーにしています。動的な内容(ユーザーメッセージ、現在日時)をキャッシュ対象のシステムプロンプトより前に置くと、キャッシュは当たりません。静的で大きなブロックを最初に、動的な内容を末尾に置いてください。

大規模で安定した文脈には拡張キャッシュ(TTL 1 時間)を使う

標準のエフェメラルキャッシュは 5 分です。文脈が大きく(コードベース全体のインデックスなど)、変更頻度が低いなら、Anthropic は TTL 1 時間の拡張キャッシュを提供しています。キャッシュ書込単価はやや上がりますが、1 時間あたりの読込単価は下がります。10 万トークンを超える文脈なら検討の価値があります。

長時間 Claude Code セッションでは CLAUDE.md をキャッシュする

Claude Code セッションでは CLAUDE.md の内容が毎メッセージに先頭付与されます。CLAUDE.md が 5,000 トークンなら、1 ターンごとに 5,000 トークンが課金対象です。CLAUDE.md は痩身に保ち、プロジェクト固有の文脈は別ファイルに切り出して、毎ターン挿入するのではなく必要時のみ参照する構成を検討してください。

分類・ルーティングタスクには Haiku を使う

Haiku 3.5 の入力単価は 100 万トークン $0.25、Sonnet 4.5 の $3 と比べて格段に安価です。本質的にパターンマッチングであるタスク(エラー分類、課題のカテゴリ分け、文章が条件に合致するかの判定など)では、Haiku は 12 分の 1 の価格で同等の品質を出します。サブエージェントを総点検してください — 最大 3 ターン、分類スタイル出力のものは Haiku 上で動かすべきです。

推論が必要な場面でのみ Sonnet を使う

Sonnet が金額に見合う場面:コードレビュー、セキュリティ監査、多段階推論、矛盾する情報の総合判断。割に合わない場面:ドキュメント生成、変更履歴の文章化、構造化データ抽出、決定論的な書式を持つ任意の作業。

各エージェントの max_tokens を控えめに設定する

API は要求トークン数ではなく、生成トークン数で課金します。とはいえ、必要のないところに大きな max_tokens を設定すると、Claude が必要以上に出力する可能性があります。構造化出力(JSON、YAML、表)では、低めの max_tokens は Claude の簡潔さを促進します。各エージェントの実出力長を計測し、max_tokens は観測 p95 出力の 120% に設定してください。

長文出力にはストリーミングを使い、必要なら早期キャンセルする

ストリーミング利用時は、十分な出力が揃った時点で途中キャンセルが可能です。API は途中までストリーミング配信されたレスポンスを、max_tokens ではなく実際に生成された分のトークンで課金します。長文出力の冒頭部分のみが必要なケースが多いアプリケーションでは、ストリーミング + 早期キャンセルで出力トークンコストを 40〜70% 削減できます。

Sonnet で十分なタスクに Opus を使わない

Opus の入力単価は 100 万トークンあたり $15 — Sonnet の 5 倍です。Opus と Sonnet の品質差は、自由度の高い創造的作業や複雑な多段階推論では確かに大きい。しかしコードタスク、構造化出力、多くの開発ワークフローでは、Sonnet は Opus と同等品質を 5 分の 1 の価格で出します。Opus を既定にする前にベンチマークしてください。

長時間セッションが 50K トークンを超える前に /compact を実行する

Claude Code の /compact コマンドは、セッションの文脈を要約し圧縮版に置き換えます。10 万トークンのセッションが 5,000 トークンの要約になります。タスク継続性に対する品質低下は最小限で、コスト削減効果は大きい。アクティブセッションでは 2 時間ごとに実行してください。

コードベース探索を Claude に任せず、Grep と Read で誘導する

方向性なく Claude にコードベースを探索させると、文脈把握のために多数のファイルを読みます。最初に関連ファイルを指定すれば(「app/api/users.ts と User モデルを読んで」)、文脈は一桁少なく済みます。Claude にファイルを読ませる前に Grep で関連箇所を絞り込んでください。

CLAUDE.md は 300 行以下に保つ

CLAUDE.md の各行は、Claude Code セッションの全メッセージに先頭付与されるトークンです。3,000 行の CLAUDE.md は毎ターン およそ 4,500 トークンを上乗せします。300 行なら およそ 450 トークンです。網羅性を犠牲にせず最小トークン消費に整える方法は、3000 行 CLAUDE.md 問題の記事をご覧ください。

サブエージェントのツールアクセスを必要最小限に絞る

全ツールへのアクセスを持つサブエージェントは、それを使います。[Read, Grep] しか持たないサブエージェントは、Bash プロセスを立ち上げて 10MB のログファイルを文脈に流し込めません。ツール制限はコストガードレールであり、同時にセキュリティ統制でもあります。

レビュー用エージェントには差分のみを渡す(全文ではなく)

コードレビューエージェントを動かす際、ファイル全体ではなく git diff HEAD~1 の出力を渡してください。40 行が変更された 2,000 行のファイルは、全文渡しなら 2,000 トークン、差分渡しなら 200 トークンです。レビュー用途では、差分でほぼ十分です。

時間制約のないワークロードはすべて Batch API に回す

Anthropic の Batch API は、リアルタイム API よりトークン単価が 50% 安い。1 バッチで最大 10,000 リクエスト、24 時間以内に処理されます。60 秒以内のレスポンスが不要な用途なら、Batch API が正解です。文書解析、テスト生成、変更履歴文章化 — いずれもバッチ向きです。

API 呼び出し前に重複リクエストを検出する

同じプロンプトを二度送りうるアプリケーション(同じユーザークエリ、同じドキュメント解析)では、API を呼ぶ前にローカルハッシュと照合してください。(model + system_prompt + user_message) の SHA-256 ハッシュで重複を識別し、ハッシュをキーにレスポンスをキャッシュします。高トラフィックなアプリで重複率 5% でも、月で見れば大きな節約です。

類似リクエストを 1 つのマルチパートプロンプトに束ねる

20 件のドキュメントに同じ操作(要約、分類、抽出)を行うなら、複数ドキュメントの 1 リクエストは、20 個の単一ドキュメントリクエストよりも安く済むことが多い — システムプロンプト分が 1 回で済むためです。実際のトークン算術で検証してください — バッチが大きすぎると文脈上限を超え、結局分割が必要になります。

同一の同時クエリにはリクエスト合流を実装する

高トラフィックアプリでは、同じ API 呼び出しを複数ユーザーが同時にトリガーする(同じレポート、同じ解析)ことがあります。リクエスト合流とは、ある呼び出しが進行中なら、それ以降の同一リクエストは結果を待って共有する手法です。トラフィックスパイクのパターンに比例して API 呼び出しを節約できます。

Batch API の優先度を上げるためオフピーク時間帯にスケジュールする

Batch API の処理時間は Anthropic 側の負荷で変動します。低トラフィック時間帯(UTC 02:00〜08:00)に投入すると、追加コストなしで完了が早まる傾向にあります。24 時間以内処理のバッチを深夜に投入し、朝に結果を受け取る運用は、信頼性の高いパターンです。

PreToolUse フックでセッション単位・日次の予算上限を設ける

PreToolUse フックは、すべてのツール呼び出しの直前に走ります。30 行ほどのフックで、セッションの累積コストを ~/.claude/projects/ から読み取り、$10 を超えたら停止する仕組みを実装すれば、トークン黙示録のシナリオを防げます。フックは API 呼び出しがマシンを離れる前に発火するため、これより手前で止める方法はありません。

すべてのサブエージェントに max_turns を設定する

max_turns 制限のないサブエージェントは無限に走り得ます。多くのエージェントには max_turns: 10 を、単純で範囲の限定されたエージェントには max_turns: 5 を設定してください。50 ターン暴走したサブエージェントは、適切に制限したものと比べて、同じタスクで 5〜10 倍のコストになります。

月次合計だけでなく、コスト異常をログ・通知する

月次請求アラートでは、トークン黙示録イベントは被害発生後にしか捕まりません。日次コストアラート(日次支出がベースラインの 2 倍を超えたら、メールや Slack Webhook で通知)なら、介入が間に合います。Anthropic コンソールには日次支出閾値アラート機能があります。設定してください。

蓄積する前にゾンビセッションを終了する

開きっぱなしの Claude Code セッションは、サブエージェントがツールを呼び出すたびに課金されます。claude sessions list でアクティブセッションを確認し、使っていないセッションは終了してください。開発者で共有するマシンでは、ゾンビセッションは見えにくく、しかも積み重なるコスト源です。