「なぜ Claude Code のリクエストには毎回 40 万もの入力トークンが含まれているのか？ なぜ請求額がこんなに高いのか？」——これは、多くの Claude Code ユーザーが利用統計を確認した際に抱く最初の疑問です。実際には、この 40 万トークンの大部分はすでにキャッシュヒットしており、実際のコストは表示されている数字の 1/10 程度である可能性があります。しかし、キャッシュがヒットしなかった場合、その請求額は確かに頭の痛い問題となります。
核心的価値: 本記事を読み終えることで、Claude Code の自動キャッシュメカニズム、キャッシュが無効化される 8 つの一般的な原因、そして入力トークンを 40 万から 5 万まで削減するための 6 つの実践的なテクニックを理解できます。
title: Claude Code の Prompt Caching（プロンプトキャッシュ）自動化メカニズムを徹底解説
description: Claude Codeで利用可能なPrompt Cachingの仕組み、コスト削減効果、およびキャッシュがヒットしない原因と対策を詳しく解説します。
Claude Code の Prompt Caching 自動キャッシュメカニズムを徹底解説
Claude Code は自動的にキャッシュを利用しますか？
はい、利用します。 Claude Code は、すべての API リクエストにおいて Anthropic の Prompt Caching を自動的に有効化します。これは組み込みの動作であり、オプション設定ではありません。
Claude Code でメッセージを送信するたびに、API に送信される内容は以下の順序で構成されます。
| 順序 | 内容 | 推定サイズ | キャッシュ動作 |
|---|---|---|---|
| 第 1 層 | ツール定義（Read/Edit/Bash 等） | ~5,000 トークン | ほぼ不変、高いヒット率 |
| 第 2 層 | システムプロンプト + CLAUDE.md | ~3,000-10,000 トークン | セッション内不変、高いヒット率 |
| 第 3 層 | 対話履歴（過去の全メッセージ） | 継続的に増加 | プレフィックス一致、段階的に蓄積 |
| 第 4 層 | 現在の新しいメッセージ | 可変 | キャッシュヒットなし |
重要なメカニズム: キャッシュはプレフィックス（接頭辞）一致に基づいています。リクエストの最初の N トークンが以前にキャッシュされた内容と完全に一致すれば、その N トークンはキャッシュから読み込まれます。継続的な対話において、20 ターン目には入力トークンの 95% 以上がキャッシュヒットによるものとなるのが一般的です。
キャッシュの価格：なぜキャッシュヒットが重要なのか
| 操作タイプ | 基本入力価格との比較 | Sonnet 4 実価格/MTok | Opus 4 実価格/MTok |
|---|---|---|---|
| 通常入力（キャッシュなし） | 1x | $3.00 | $15.00 |
| 5分キャッシュ書き込み | 1.25x | $3.75 | $18.75 |
| 1時間キャッシュ書き込み | 2x | $6.00 | $30.00 |
| キャッシュヒット/読み込み | 0.1x | $0.30 | $1.50 |
| 出力 | — | $15.00 | $75.00 |
具体的な例: リクエストの入力トークンが 40 万トークンの場合：
シナリオ A：キャッシュなし
├── 40万 トークン × $3/MTok (Sonnet) = $1.20 / リクエスト
シナリオ B：95% キャッシュヒット（典型的な Claude Code セッション）
├── キャッシュヒット 38万 トークン × $0.30/MTok = $0.114
├── キャッシュ書き込み 1万 トークン × $3.75/MTok = $0.0375
├── 新規入力 1万 トークン × $3/MTok = $0.03
├── 合計 = $0.18 / リクエスト
└── 実質コストはキャッシュなしの 15% にまで削減
🎯 技術ヒント: APIYI (apiyi.com) を通じて Claude API を呼び出す場合も Prompt Caching メカニズムがサポートされており、キャッシュヒット時の入力コストを 90% 削減できます。API で Claude を統合しているプロジェクトでは、キャッシュヒット率を最大化するためにプロンプト構造を最適化することをお勧めします。
キャッシュ TTL：Max ユーザーの隠れたメリット
| プラン | キャッシュ TTL | 書き込みコスト | 説明 |
|---|---|---|---|
| API 従量課金 | 5 分 | 1.25x | 5 分間操作がないとキャッシュ失効 |
| Pro / Team | 5 分 | 1.25x | 同上 |
| Max 5x / 20x | 1 時間 | 2x | 書き込みは高いがヒット有効期間が 12 倍 |
Max ユーザーはキャッシュ書き込み価格が 2 倍（標準の 1.25 倍より高い）ですが、1 時間の TTL があるため、コーヒーを飲んで戻ってきてもキャッシュが有効なままです。断続的に作業する開発者にとって、この差は非常に大きいです。
キャッシュヒットが発生するたびに TTL タイマーがリセットされるため、アクティブに使用し続けていればキャッシュが切れることはほぼありません。
キャッシュがヒットしない？8 つのよくある原因と解決策
キャッシュが失効する根本的な原因はただ一つ、「リクエストのプレフィックスがキャッシュ内容と一致しない」ことです。Claude Code においては、以下の 8 つのケースでキャッシュが失効します。
第 1 カテゴリ：TTL 失効
| 原因 | トリガー条件 | 影響範囲 | 解決策 |
|---|---|---|---|
| 1. アイドルタイムアウト | API ユーザー 5 分以上、Max ユーザー 1 時間以上操作なし | 全キャッシュ失効 | アクティブな状態を維持する |
これは最も一般的な失効原因です。コーディング中に 5 分（API ユーザー）または 1 時間（Max ユーザー）以上離席すると、次回の操作でキャッシュが再構築されます。
第 2 カテゴリ：内容変更による連鎖的な失効
キャッシュは厳格な階層構造に従います：ツール定義 → システムプロンプト → 対話履歴。上位層が変更されると、下位層はすべて失効します。
| 原因 | トリガー条件 | 影響範囲 | 深刻度 |
|---|---|---|---|
| 2. モデルの切り替え | /model コマンドの使用 |
全キャッシュ（モデルごとに隔離） | ⚠️ 高 |
| 3. MCP ツールの追加/削除 | MCP サーバーのインストール/アンインストール | ツール層以降すべて | ⚠️ 高 |
| 4. Web 検索の切り替え | 検索機能のオン/オフ | システム層以降すべて | ⚠️ 中 |
| 5. CLAUDE.md の修正 | 設定ファイル編集後の再起動 | システム層以降すべて | ⚠️ 中 |
第 3 カテゴリ：操作による失効
| 原因 | トリガー条件 | 影響範囲 | 深刻度 |
|---|---|---|---|
| 6. 新規対話 | /clear または新規セッション開始 |
全キャッシュ（対話履歴が空になる） | ⚠️ 高 |
| 7. /compact の使用 | 対話履歴の能動的な圧縮 | 対話履歴層のキャッシュ失効 | ⚠️ 中 |
| 8. /rewind の使用 | メッセージの取り消し | 対話履歴のプレフィックス変更 | ⚠️ 中 |
見落としがちな技術的制限：最小キャッシュ長
プロンプトが以下のトークン数未満の場合、キャッシュは警告なしにスキップされます。
| モデル | 最小キャッシュ長 |
|---|---|
| Claude Opus 4.6 / Haiku 4.5 | 4,096 トークン |
| Claude Sonnet 4.6 | 2,048 トークン |
| Claude Sonnet 4.5 / 4 | 1,024 トークン |
Claude Code の場合、ツール定義とシステムプロンプトだけで 5,000 トークンを超えるため、この制限に引っかかることはほとんどありません。しかし、API を通じて独自にアプリケーションを構築する場合は、この下限に注意が必要です。
💡 推奨: APIYI (apiyi.com) を通じて Claude API を呼び出すアプリケーションを自作する場合、システムプロンプトの長さがモデルごとの最小キャッシュしきい値を超えていることを確認してください。そうでないとキャッシュが有効になりません。
description: Claude Codeで「40万入力トークン」という驚きの数字が表示される理由を解説。トークンの内訳や、会話履歴・ツール呼び出し・キャッシュの仕組みを紐解きます。
40万入力トークンの正体：Claude Codeのコンテキスト構成
キャッシュの仕組みを理解したところで、あなたを驚かせた「40万入力トークン」が具体的に何で構成されているのかを分解してみましょう。
トークン消費の5つの主なソース
| ソース | 割合 | 40万中の目安 | 特徴 |
|---|---|---|---|
| 会話履歴の蓄積 | ~60% | ~24万 | 会話ごとに全履歴を再送信 |
| ツール呼び出し結果 | ~20% | ~8万 | ファイル読み込みやgrep検索結果がコンテキストに常駐 |
| 拡張推論チェーン | ~10% | ~4万 | 前のラウンドの思考ブロック（thinking block）が入力になる |
| システムプロンプト + CLAUDE.md | ~5% | ~2万 | 全メッセージに付随 |
| ツール定義 | ~5% | ~2万 | 利用可能な全ツールのスキーマ |
核心的な事実：会話が長くなるほど、入力は増える
Claude Codeの動作は、リクエストのたびに会話履歴全体を再送信するというものです。つまり：
- 第1ラウンド：入力 ~2万トークン（システムプロンプト + ツール定義 + あなたの質問）
- 第5ラウンド：入力 ~10万トークン（4ラウンド分の会話履歴が蓄積）
- 第15ラウンド：入力 ~25万トークン（大量のファイル読み込み結果を含む）
- 第30ラウンド：入力 ~40万トークン以上（自動圧縮の閾値に到達）
ただし注意点があります：これらの入力の大部分はキャッシュヒットしています。第30ラウンドの40万トークンのうち、実際に新しく追加された非キャッシュコンテンツは1〜2万トークン程度である可能性があります。
大規模コードベースにおける特有の問題
Claude Codeは、コードベース全体を自動的にコンテキストに読み込むことはしません。必要に応じてファイルを読み込みます。しかし、大規模なコードベースでは以下のことが起こります：
- 1回の
grep検索で大量の結果が返り、すべてがコンテキストに入る - 探索的に複数のファイルを読み込み、各ファイルの内容が会話履歴に常駐する
- エージェントモードが自律的に多ステップの操作を実行し、各ステップのツール呼び出し結果が蓄積される
あなたの環境で毎回40万トークンに達する場合、以下の要因が重なっている可能性が高いです：
- コードベースが大きく、Claude Codeが分析のために大量のファイルを読み込んでいる
- 会話ラウンド数が多く、履歴が蓄積されている
/compactや/clearコマンドを適宜使用していないCLAUDE.mdファイルが長大である
description: 大規模言語モデルの入力トークンを40万から5万に削減するための6つの実践的テクニックを紹介します。Claude Codeの最適化やコスト削減に役立つヒントをまとめました。
実践テクニック6選：入力トークンを40万から5万に削減する方法
テクニック1：プロンプトを具体的にし、全体スキャンを避ける
これは最も重要かつ実行しやすい最適化です。
❌ 曖昧な指示（広範囲のファイルスキャンを誘発）：
"このプロジェクトのパフォーマンスを最適化して"
"コード内のバグをチェックして"
"このモジュールをリファクタリングして"
✅ 具体的な指示（必要なファイルのみを読み込む）：
"src/api/handler.ts の processRequest 関数の応答時間を最適化して"
"src/auth/login.ts の 45 行目にある NullPointerException を修正して"
"src/utils/format.ts の formatDate 関数を moment から dayjs に移行して"
曖昧な指示を出すと、Claude Code は Glob + Grep + Read を使用して大量のファイルを読み込み、あなたの意図を「理解」しようとします。その結果、すべてのファイル内容が会話履歴に永続的に残ってしまいます。具体的な指示を出せば、関連する1〜2ファイルのみを読み込ませることができます。
トークン節約効果：ツール呼び出し結果のトークンを 60〜80% 削減
テクニック2：/clear と /compact を適宜活用する
# 無関係なタスクに切り替える際、会話をクリアする
/clear
# 会話は長いがタスクがまだ終わっていない場合、履歴を圧縮する
/compact
# 指示付きで圧縮し、特定の情報を保持する
/compact コード例と API インターフェース定義を保持し、その他は簡潔にまとめて
| コマンド | 効果 | 推奨シーン | 注意点 |
|---|---|---|---|
/clear |
会話履歴をすべて消去 | 全く別のタスクに切り替える時 | キャッシュがすべて無効になる |
/compact |
AI が履歴を要約し、原文を置換 | 長い会話の途中段階 | キャッシュの一部が無効になるが、コンテキストは大幅に縮小される |
実際の効果：40万トークンの会話でも、/compact を実行すれば通常 5〜8万トークンまで圧縮可能です。
テクニック3：CLAUDE.md ファイルを最適化する
CLAUDE.md はすべてのメッセージで読み込まれます。10,000トークンの CLAUDE.md がある場合、30回のやり取りで30回送信されることになります（キャッシュヒットにより費用は 0.1倍になりますが、貴重なコンテキスト容量を占有し続けます）。
最適化のヒント：
├── CLAUDE.md を 500 行以内に収める（コアルールのみ）
├── 詳細なワークフロー説明は Skills に移動する（必要に応じて読み込み）
├── 参考ドキュメントは knowledge-base/ に配置する（必要な時に Read）
└── CLAUDE.md 内に長いサンプルコードを置かない
🚀 実践アドバイス: CLAUDE.md を簡潔にすることは、トークン消費を抑えるだけでなく、Claude Code がコアルールに集中しやすくなるメリットもあります。もし APIYI (apiyi.com) を使って同様の AI コーディングアシスタントを構築している場合も、システムプロンプトの長さを制御することをお勧めします。
テクニック4：Subagent を使って冗長な出力を分離する
大量の出力が発生する操作を行う際は、直接実行するのではなく Subagent を活用しましょう。
❌ メインの会話で直接実行（出力すべてがメインコンテキストに入る）：
"テストスイートを実行して失敗の原因を分析して"
→ テスト出力が 50,000+ トークンに達し、会話履歴に永続的に残る
✅ Claude Code に Subagent を使わせる（出力はサブプロセスに隔離）：
"サブタスクを使ってテストスイートを実行し、失敗したテスト名と原因だけをまとめて教えて"
→ メインコンテキストには約 500 トークンの要約のみが追加される
トークン節約効果：1回の操作でメインコンテキストに入るトークンを 10,000〜50,000 削減可能
テクニック5：適切なモデルと effort レベルを選択する
| タスクの種類 | 推奨モデル | effort レベル | 説明 |
|---|---|---|---|
| 単純な修正/フォーマット | Sonnet | low | 深い思考は不要 |
| 通常の開発 | Sonnet | medium | コスパが最高 |
| 複雑なアーキテクチャ設計 | Opus | high | 深い推論が必要 |
| コードレビュー | Sonnet | medium | Opus よりコスパが良い |
# 思考の深さを下げ、thinking トークンを減らす（後にこれが入力トークンになる）
# 単純なタスクでは低い effort を設定する
/effort low
# または環境変数で思考トークンの上限を制御する
MAX_THINKING_TOKENS=8000
拡張された思考プロセス (thinking) は、後のラウンドで入力トークンの一部となります。effort レベルを下げることで、後のラウンドで蓄積されるトークンを大幅に減らすことができます。
テクニック6：/context コマンドでトークンの分布を監視する
# 現在のトークン使用分布を確認する
/context
/context コマンドは、現在のコンテキストにおける各パーツのトークン占有率を表示し、何が容量を消費しているかを特定するのに役立ちます。よくあるケース：
- grep 検索の結果、20,000 トークンが返されたが、役に立ったのは 5% だけだった
- 以前読み込んだ大きなファイルが不要になったのにコンテキストに残っている
- CLAUDE.md が予想以上に容量を占有している
問題を発見したら、必要に応じて /compact や /clear で対処しましょう。
💰 コストアドバイス: API の従量課金ユーザーにとって、これらの最適化テクニックは直接的な請求額削減につながります。APIYI (apiyi.com) プラットフォームの利用統計機能を使えば、リクエストごとのトークン分布が明確に確認できるため、コストの発生源を特定するのに役立ちます。
実践事例：日次コストを60ドルから8ドルへ削減
以下は、実際の最適化プロセスの事例です。
最適化前（大規模Pythonプロジェクト、Claude Codeヘビーユーザー）
日次利用状況：
├── 会話ターン数：約50回/日
├── 平均入力トークン数：35-45万トークン/ターン
├── キャッシュヒット率：約70%（頻繁な /clear やモデル切り替えによるもの）
├── 日次APIコスト（Opus 4）：約60ドル
└── 月次コスト：約1,320ドル
最適化後（6つのテクニックを適用）
日次利用状況：
├── 会話ターン数：約40回/日（より的確になり、回数が減少）
├── 平均入力トークン数：8-12万トークン/ターン（的確なプロンプト + 定期的な compact）
├── キャッシュヒット率：約92%（不要なキャッシュの中断を削減）
├── 日次APIコスト（Sonnet 4がメイン、Opusは複雑なタスクのみ）：約8ドル
└── 月次コスト：約176ドル
| 最適化項目 | 削減割合 | 説明 |
|---|---|---|
| 曖昧なスキャンから的確なプロンプトへ | 約35% | 最大の改善項目 |
| 適切なタイミングでの /compact と /clear | 約25% | 蓄積による肥大化を抑制 |
| OpusからSonnetへ移行（タスクの80%） | 約20% | モデルダウングレードによる影響なし |
| CLAUDE.mdの簡素化 | 約8% | ターンごとの固定オーバーヘッドを削減 |
| サブエージェントによる冗長な出力の分離 | 約7% | 大量の結果によるコンテキスト汚染を回避 |
| effortレベルの引き下げ | 約5% | 思考トークンの蓄積を抑制 |
よくある質問
Q1: Claude Codeに表示される40万トークンは、実際に40万トークン分課金されますか？
いいえ。Claude Codeは自動的にプロンプトキャッシュを有効にします。アクティブなセッションでは、入力トークンの95%以上がキャッシュヒットとなることが多く、その場合の料金は基本価格の0.1倍に抑えられます。40万トークンのうち、実際にフルプライスで課金されるのは2〜4万トークン程度かもしれません。/context コマンドで実際のキャッシュヒット率を確認できます。APIYI (apiyi.com) を経由したAPI呼び出しでも、同様にキャッシュ機能がサポートされています。
Q2: Maxプラン（月額制）を利用していてもトークン消費を気にする必要がありますか？
気にする必要がありますが、理由は異なります。Maxプランはトークン単位の課金ではありませんが、週ごとの利用上限があります。トークン消費量が多すぎると、すぐに制限に達してしまいます。コンテキストを簡素化することは、利用可能時間を延ばすだけでなく、Claude Codeがあなたの意図をより正確に理解する助けにもなります（コンテキストが的確であればあるほど、回答の質も向上します）。
Q3: /compact と /clear はどちらが良いですか？
状況によります。全く別のタスクを開始する場合は、/clear で完全にリセットするのが最適です。同じタスクを継続しているものの、会話が長くなりすぎた場合は、/compact を使って重要なコンテキストを残しつつボリュームを圧縮するのが良いでしょう。/compact は「すべてのコード修正履歴とAPIインターフェース定義を保持する」といったカスタム指示にも対応しています。
Q4: 最新版のClaude Codeにアップデートすると、自動的にトークン使用量は最適化されますか？
はい、常に最新バージョンに保つことをお勧めします。AnthropicはClaude Codeのコンテキスト管理戦略を継続的に改善しています。例えば、自動圧縮のトリガータイミング（現在はコンテキストの約83.5%を占有した際にトリガー）、MCPツール定義の遅延読み込み（ツール名のみ読み込み、使用時にスキーマ全体を読み込む）などです。新しいバージョンは通常、より高いキャッシュヒット率と、よりスマートなコンテキスト管理を実現します。
まとめ：キャッシュの理解 + 正確な活用 = コスト管理の最適化
Claude Code のプロンプトキャッシュ（Prompt Caching）は、非常に強力な自動最適化メカニズムです。特別な設定をせずとも、自動的にコストを削減してくれます。 しかし、その仕組みとキャッシュが無効になる条件を理解することで、コスト削減効果を「自動的な70%」から「戦略的な95%」へと引き上げることが可能です。
以下の3つの核心原則を覚えておきましょう：
- キャッシュをアクティブに保つ: 不要な操作でキャッシュを中断させない（頻繁なモデルの切り替えや、無闇な
/clearを避ける） - コンテキストの肥大化を抑制する: 的確なプロンプトと定期的な
/compactを活用し、会話履歴が際限なく増大するのを防ぐ - ツールとモデルを適切に選ぶ: 80% のタスクは Sonnet で十分です。Opus は本当に必要なシーンのために取っておきましょう
APIの従量課金ユーザーには、APIYI（apiyi.com）を通じて Claude API の呼び出しを一元管理し、プラットフォームの利用量監視機能を使ってトークン消費を継続的に最適化することをお勧めします。また、対話型ツールを多用するユーザーには、Claude Max の月額プランを契約し、本記事の最適化テクニックを組み合わせることで、最高のコストパフォーマンスを得ることを推奨します。
📝 執筆者: APIYI 技術チーム | APIYI apiyi.com – 300種類以上のAI大規模言語モデルAPIを一元管理できるプラットフォーム
参考資料
-
Anthropic Prompt Caching ドキュメント: キャッシュメカニズムの詳細解説
- リンク:
docs.anthropic.com/en/docs/build-with-claude/prompt-caching - 説明: キャッシュのTTL、料金倍率、最小長要件について
- リンク:
-
Claude Code コスト管理ガイド: トークン最適化に関する公式アドバイス
- リンク:
code.claude.com/docs/en/costs - 説明: Anthropic 公式が推奨するコスト管理戦略
- リンク:
-
Claude Code ベストプラクティス: コンテキスト管理と効率化
- リンク:
anthropic.com/engineering/claude-code-best-practices - 説明: 的確なプロンプトや
compactの使用など、実践的なアドバイスを掲載
- リンク:
