費用最適化ガイド

Claude Code のコスト管理テクニックをマスターし、より少ないトークンでより多くの作業を完了する

費用最適化ガイド¶

Claude Code でコードを書くのは爽快ですが、使い方に注意しないと請求書に「サプライズ」が待っているかもしれません。このガイドでは、費用がどのように発生するのか、そして効率を犠牲にせずにコストを適切にコントロールする方法を理解できるよう手助けします。

Token 課金の理解¶

費用を最適化する前に、まず費用の根本的なロジックである Token を理解する必要があります。

Token とは¶

Token は AI モデルがテキストを処理する最小単位です。モデルの「文字」だと考えてください：

• 英語：1 Token は約 4 文字、または 0.75 単語に相当
• 中国語：1 文字は約 1〜2 Token（平均約 1.5 Token）
• コード：変数名、キーワード、記号はそれぞれ異なる量の Token を消費

簡単な見積もりの参考：

入力 vs 出力 Token¶

Claude と対話するたびに、費用は次の 2 つの部分で構成されます：

総費用 = 入力 tokens × 入力単価 + 出力 tokens × 出力単価

重要なポイント：出力 token の価格は通常、入力 token の 5 倍です。Sonnet 4.6 を例にとると：

つまり、Claude に長い文章を生成させる方が、大量のコンテキストを提供するよりも高価だということです。

典型的な会話で消費される Token 量¶

Sonnet 4.6 を例に、いくつかの一般的なシナリオの費用を見積もります：

上記の数字はあくまで参考であり、実際の費用はコード量、会話のターン数、コンテキストのサイズによって異なります。

モデル選択戦略¶

正しいモデルを選ぶことが最も直接的な節約方法です。モデル間の価格差は非常に大きいです。

3 種類のモデルの位置づけ¶

費用比較：同じ中程度の複雑さのタスク（入力 10K、出力 3K tokens）を完了する場合：

• Haiku：$0.025
• Sonnet：$0.075
• Opus：$0.125

Sonnet は Haiku の 3 倍、Opus は Haiku の 5 倍です。

モデル選択の原則¶

日常は Sonnet を第一選択（80% のタスクはこれで十分）

以下のシナリオでのみ Opus に切り替え：

  - 複雑なアーキテクチャ設計と技術的意思決定
  - 大規模なコードリファクタリング
  - 複数のシステムにまたがるモジュール横断の修正
  - 深い推論が必要な難解なバグ

以下のシナリオでのみ Haiku に切り替え：

  - 単純なフォーマット変換
  - 反復的なコード生成（例：CRUD インターフェース）
  - 高速 Q&A（一言で答えられる質問）
  - コードコメントとドキュメント生成

/model コマンドでいつでも切り替え可能：

/model sonnet    # Sonnet に切り替え
/model opus      # Opus に切り替え
/model haiku     # Haiku に切り替え

コンテキスト管理による節約テクニック¶

コンテキスト管理は費用最適化の核心です。各ターンの会話で、Claude はそれまでのすべての会話履歴を再送信します。つまり、会話が長くなるほど、各ターンの入力 token が増えていきます。

/compact で履歴を圧縮¶

会話が 10 ターン以上になったとき、あるいは応答が遅くなったと感じたら、/compact を使って圧縮します：

/compact

/compact を使うと、Claude がそれまでの会話を簡潔なサマリーにまとめ、完全な履歴の代わりにします。これにより、次のターンの会話の入力 token が大幅に削減されます。

使用のタイミング：

• 会話が 10 ターンを超えた場合
• サブタスクが完了し、次のサブタスクを始める準備ができた場合
• Claude の応答品質が低下していると感じたとき（コンテキスト過負荷のシグナル）

/clear で完全にクリア¶

まったく異なるトピックに切り替えるときは、迷わず /clear を使いましょう：

/clear

使用のタイミング：

• 機能 A の開発から機能 B に切り替える場合
• デバッグが完了し、新しいコードを書き始める場合
• 会話が方向からそれてしまい、最初からやり直したい場合

/clear を使わない代償：仮にそれまでの会話履歴が 50K tokens あるとすると、トピックを変えても各ターンの会話でこの 50K tokens のためにムダな料金を払い続けることになります。Sonnet で計算すると、1 ターンあたり追加で $0.15 の費用が発生します。会話を 10 ターンすれば $1.5 がムダになります。

精密な @ 参照¶

Claude に自分でファイルを検索させるのと、あなたが直接ファイルを参照させるのとでは、cost が大きく異なります：

# 高価！Claude は関連コードを見つけるために数十ファイルを検索する可能性がある
"ユーザー登録ロジックのメール検証部分を修正して"

# 安価！Claude にどこを変更するか直接伝える
"@src/services/auth-service.ts の validateEmail メソッドの正規表現を修正して"

どのファイルを変更すべきか分かっているときは、常に @ を使って直接参照してください。Claude に自分で検索させるのは高価なだけでなく、結果も必ずしも正確とは限りません。

.claudeignore で大きなファイルを排除¶

以下のタイプのファイルが .claudeignore に含まれていることを確認してください：

# これらのファイルが Claude に読み込まれると、大量の token を消費する
node_modules/          # 数万ファイルにのぼることも
dist/                  # ビルド成果物
*.min.js               # 圧縮された JS
*.sql                  # データベース dump
*.csv                  # データファイル
package-lock.json      # ロックファイル（内容が巨大）
pnpm-lock.yaml         # ロックファイル
yarn.lock              # ロックファイル

実際のケース：あるユーザーが費用が異常に高いことに気づき、調査した結果、Claude がコードを検索する際に 50MB の SQL dump ファイルを読み込んでおり、一度で約 15M tokens（約 $45 の入力費用）を消費していたことが判明しました。

キャッシュメカニズムの活用¶

Prompt Caching は Claude API の非常に重要な節約機能です。

Prompt Caching とは¶

連続した多ターンの会話では、各ターンでそれまでのすべての内容が再送信されます。キャッシュがなければ、毎回完全な入力価格で課金されます。キャッシュがあれば：

• 初回送信：通常の入力価格（キャッシュ書き込み価格はやや高い）
• 以降の送信：同じ内容はキャッシュにヒットし、キャッシュ読み取り価格（1/10 のみ）

Sonnet 4.6 を例にとると：

つまり、キャッシュヒット時は 1/10 の価格で済むということです。

キャッシュをうまく活用する方法¶

キャッシュは自動的に有効になりますが、使用習慣によってキャッシュヒット率を高めることができます：

会話を連続させる：

# 良い習慣：同じ機能の開発を同一の会話で続ける
> "UserService の基本構造を作成"
> "getUserById メソッドを追加"        # 前の内容がキャッシュにヒット
> "updateUser メソッドを追加"         # 前の内容がキャッシュにヒット
> "ユニットテストを追加"               # 前の内容がキャッシュにヒット

# 悪い習慣：一言話すたびに /clear
> "UserService の基本構造を作成"
> /clear
> "UserService に getUserById メソッドを追加"    # キャッシュを利用できない
> /clear
> "UserService に updateUser メソッドを追加"     # キャッシュを利用できない

CLAUDE.md を頻繁に変更しない：

CLAUDE.md の内容は各ターンで送信されます。内容が安定していれば、長期的にキャッシュにヒットします。頻繁に変更するとキャッシュが無効になります。

適切な /compact のタイミング：

/compact は履歴を置き換えるため、キャッシュが無効になります。だからあまり頻繁に使わないでください——会話が本当に長くなったときだけ使いましょう。

キャッシュの効果はどれほどか¶

仮に 10 ターンの会話で、各ターンの入力が約 20K tokens（履歴を含む）だとすると：

キャッシュにより、入力費用の約 80% を節約できます。

監視と予算¶

費用を監視する習慣を身につけ、知らないうちに使いすぎてしまうのを避けましょう。

/cost で現在のセッションを確認¶

Claude Code でいつでも次のように入力：

/cost

現在のセッションで消費された token 数と見積もり費用が表示されます。各タスクを完了するたびに確認することをお勧めします。

QCode.cc Dashboard で履歴を確認¶

QCode.cc コンソール にログインし、「使用統計」ページで以下を確認できます：

• モデル呼び出しの明細：各呼び出しのモデル、token 数、費用
• 日別/月別の集計：費用トレンドグラフ
• プラン消費の進捗：現在のプラン枠の使用率

毎日 Dashboard を確認する習慣を身につけ、異常な消費を早期に発見しましょう。

費用管理のアドバイス¶

よくある費用の落とし穴¶

以下は最も token を浪費しやすいいくつかのケースです。自分が当てはまっていないか照らし合わせて確認してください：

落とし穴 1：大きなファイルを直接貼り付け¶

# 間違ったやり方：ファイルの内容を会話に貼り付ける
> "以下が私のコードです、チェックしてください：
[500 行のコードを貼り付け]"

# 正しいやり方：@ で参照する
> "@src/services/order-service.ts の createOrder メソッドを確認して"

違い：500 行のコードを貼り付けると約 1500 tokens の入力になり、しかも各ターンの会話でこれらの内容が繰り返し送信されます。@ で同じファイルを参照すれば、Claude は必要なときだけ読み込み、しかも読み込んだ内容はキャッシュされます。

落とし穴 2：失敗した同じコマンドを繰り返しリトライ¶

# 間違ったやり方：同じ失敗したコマンドを Claude に何度も実行させる
> "npm run build を実行"
# 失敗した
> "もう一度試して"
# やっぱり失敗
> "さらにもう一度"

# 正しいやり方：失敗原因を分析し、別の方法を取る
> "npm run build を実行"
# 失敗した
> "エラーログを確認し、失敗原因を分析して、問題を修正してから再ビルドして"

リトライするたびに完全な会話履歴（それまでのすべての失敗出力を含む）が送信され、token 消費が急速に積み重なります。

落とし穴 3：/clear を忘れてコンテキストが肥大化¶

これは最も気づきにくい費用の落とし穴です：

# 午前：バグを 1 つ修正（会話で 30K tokens の履歴が蓄積）
# 午後：新機能を書き始めるが、/clear しない
# 各ターンの新しい会話が午前の 30K tokens 履歴をムダに引きずる

# 修正：タスクを切り替えるときは /clear する習慣を
/clear
> "ここから新機能を開発します..."

落とし穴 4：簡単なタスクに Opus を使う¶

# ムダ：Opus でシンプルな interface を生成
/model opus
> "id、name、email フィールドを含む User インターフェースを定義して"

# 節約：簡単なタスクは Haiku で十分
/model haiku
> "id、name、email フィールドを含む User インターフェースを定義して"

このタスクでは両方のモデルの出力はほとんど同じですが、Opus の費用は Haiku の 5 倍です。

落とし穴 5：Claude にプロジェクト全体を検索させる¶

# 高価：Claude は数十ファイルを読み込む可能性がある
> "プロジェクトで決済を処理するコードを見つけて"

# 安価：おおよその位置を伝える
> "@src/services/ ディレクトリ下で決済を処理するサービスを見つけて"

# 最も安価：ファイルを直接指定
> "@src/services/payment-service.ts を確認して"

費用最適化チェックリスト¶

Claude Code を使うたびに、このチェックリストを確認してください：

• [ ] 適切なモデルを選んだか（大部分のタスクは Sonnet を使用）
• [ ] ファイル内容を貼り付けるのではなく、@ を使って参照しているか
• [ ] トピックを変えるときに /clear を実行したか
• [ ] 会話が 10 ターンを超えたら /compact を検討したか
• [ ] .claudeignore を設定して大きなファイルを排除したか
• [ ] 要件の説明は十分に明確か（理解のズレによる手戻りを避けるため）
• [ ] /cost を確認して現在の消費を把握したか

これらの習慣を身につければ、費用を 30〜50% 削減でき、同時に開発効率はまったく低下しないことに気づくでしょう。

Prompt キャッシュとコスト¶

前述のとおり、キャッシュヒット時の入力価格は 1/10 で済みます。ここでは「なぜそうなるのか」、そしてキャッシュの恩恵を最大化するためにコンテキストを能動的に設計する方法をさらに詳しく説明します。

キャッシュされるのは安定したプレフィックスのみ¶

Claude API の Prompt Caching がキャッシュするのは、プロンプトの安定したプレフィックス——システムプロンプト、CLAUDE.md、長い背景資料など、変化しない冒頭部分です。キャッシュにヒットすると、この部分の読み取り価格は通常の入力の約 10%（約 90% 安い）になります。重要なのは、キャッシュが「プレフィックス」単位で機能する点です。プレフィックスの前方の内容が一度変わると、その変更点以降のキャッシュはすべて無効になります。

したがって節約の核心原則は、変化しない内容を最前に置き、できるだけそれを編集しないことです。

コンテキストをキャッシュ親和的にする方法¶

• 簡潔で安定した CLAUDE.md：高シグナルな内容で、変更は少なく。CLAUDE.md を頻繁に変更すると、その後ろのキャッシュ全体が無効になり、毎回フルプライスで再計算されます。
• セッションを再利用する：同じセッション内で同じタスクを進め続ければ、プレフィックスが常に一致し、以降の各ターンでキャッシュ読み取り価格を享受できます。
• 貼り付けの代わりにパス参照を使う：内容を会話に貼り付けるのではなく @パス でファイルを参照すると、token を減らせるうえ、変わりやすい内容をプレフィックスに混ぜてキャッシュを壊すのも防げます。
• /compact は慎重に使う：/compact は履歴サマリーを書き換えるため、実質的にプレフィックスを書き換え、既存のキャッシュを無効にします——会話が本当に長すぎるときだけ使いましょう。

一言でまとめると、安定した内容を前に、変わりやすい内容を後ろに、プレフィックスを軽々しく変更しない——これが最小のコストでキャッシュ割引をフル活用する鍵です。コンテキストの階層と簡素化のテクニックについては、モデル選択ガイドの関連アドバイスを参照してください。

役割に応じたモデル選択¶

「日常は Sonnet」は良い出発点ですが、より節約できるやり方はタスクの役割に応じてモデルを選ぶことです。すべてを同じモデルで通すのではなく、各種類の作業を最もコスト効率の良いモデルで実行します。

役割ごとの分担¶

核心となる考え方は、些細なタスクに Opus を使わないことです。単純なインターフェース定義では Haiku と Opus の出力はほぼ同じですが、Opus は 5 倍高価です。重量級モデルは、本当に深い推論が必要な工程のために取っておきましょう。

セッション途中での切り替え¶

/model を使えば、セッションを開き直さずにいつでも切り替えられます：

/model haiku     # 簡単なステップは軽量モデルに切り替え
/model sonnet    # 主力モデルに戻して実装を続行
/model opus      # アーキテクチャの意思決定時に一時的にアップグレード

効率的な節約のリズムは、開発の主体を Sonnet で進め、アーキテクチャの難所に当たったら一時的に /model opus で考え、意思決定が済んだら Sonnet に戻し、まとまった単純な仕上げは Haiku に任せることです。モデルごとの詳しい能力比較と選定アドバイスは、モデル選択ガイドを参照してください。