## 費用最適化ガイド

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

## Token 課金の理解

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

### Token とは

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

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

簡単な見積もりの参考：

| 内容 | おおまかな文字数/行数 | おおまかな Token 数 |
|------|-------------|-------------|
| 短い要件説明文 | 100 文字 | ~150 tokens |
| 200 行の TypeScript ファイル | ~5000 文字 | ~1500 tokens |
| コンテキストを含む典型的な会話入力 | — | 5,000〜20,000 tokens |
| Claude Code のシステムプロンプト | — | ~8,000 tokens |

### 入力 vs 出力 Token

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

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

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

| 種類 | 価格（ドル/百万 tokens） | 1000 tokens の費用 |
|------|----------------------|-----------------|
| 入力 | $2.00 | $0.002 |
| 出力 | $10.00 | $0.010 |
| キャッシュ読み取り | $0.20 | $0.0002 |

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

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

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

| シナリオ | 入力 tokens | 出力 tokens | 見積もり費用 |
|------|-----------|-----------|---------|
| 単純な Q&A（コードの一部を説明） | 3,000 | 500 | $0.011 |
| 関数を 1 つ修正 | 8,000 | 1,500 | $0.031 |
| 新しいコンポーネントを作成（ファイル読み込み含む） | 15,000 | 3,000 | $0.060 |
| 複雑な機能開発（多ターン会話） | 50,000 | 15,000 | $0.250 |
| 大規模リファクタリング（10+ ファイル） | 200,000 | 50,000 | $0.900 |

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

## モデル選択戦略

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

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

| モデル | 入力価格 | 出力価格 | 位置づけ |
|------|---------|---------|------|
| Haiku 4.5 | $1.00 | $5.00 | 軽量高速、日常的なシンプルタスク |
| Sonnet 5 | $2.00 | $10.00 | 最適なバランス、メインモデル |
| Opus 5 | $5.00 | $25.00 | 現行フラッグシップ、4.7 と同価格 |
| Opus 4.7 | $5.00 | $25.00 | 前世代フラッグシップ、引き続き利用可能 |

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

- Haiku：$0.025
- Sonnet：$0.050
- Opus：$0.125

Sonnet 5 は Haiku の 2 倍、Opus 5 は 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 が大きく異なります：

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

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

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

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

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

```bash
# これらのファイルが 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 5 を例にとると：

| 種類 | 価格/百万 tokens | 通常の入力との比較 |
|------|----------------|------------|
| 通常の入力 | $2.00 | 100% |
| キャッシュ書き込み | $2.50 | 125% |
| キャッシュ読み取り | $0.20 | 10% |

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

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

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

**会話を連続させる**：

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

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

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

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

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

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

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

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

| | キャッシュなし | キャッシュあり（90% ヒット率） |
|---|---|---|
| 総入力 tokens | 200K | 200K |
| 通常価格で課金 | 200K | 20K |
| キャッシュ価格で課金 | 0 | 180K |
| 総入力費用（Sonnet） | $0.60 | $0.114 |
| **節約** | — | **$0.486（81%）** |

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

## 監視と予算

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

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

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

```
/cost
```

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

### QCode.cc Dashboard で履歴を確認

[QCode.cc コンソール](https://qcode.cc/dashboard) にログインし、「使用統計」ページで以下を確認できます：

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

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

### 費用管理のアドバイス

| 使用レベル | 推奨モデル戦略 | 月間予算の目安 |
|---------|-----------|----------|
| 軽度使用（毎日 1〜2 時間） | Sonnet を中心に | $30〜80 |
| 中程度使用（毎日 3〜5 時間） | Sonnet + 時々 Opus | $80〜200 |
| 重度使用（終日開発） | Sonnet を主力 + Opus でアーキテクチャ判断 | $200〜500 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```bash
# 高価：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 | 最前（安定） | 高い、長期的にヒット |
| プロジェクト規約、API ドキュメントなどの長い背景 | 前方（安定） | 高い |
| 現在のタスクの具体的な指示 | 後方 | 低い（もともと頻繁に変わる） |
| リアルタイムの会話履歴 | 末尾 | 会話とともに増加 |

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

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

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

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

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

### 役割ごとの分担

| タスクの役割 | 推奨モデル | 典型的なシナリオ |
|---------|---------|---------|
| 検索 / フォーマット / 簡単な書き換え | Haiku 4.5 | ドキュメント検索、フォーマット変換、コメント修正、一言で答えられる質問 |
| 日常的な実装 / バグ修正 | Sonnet 5 | 機能の作成、ロジックの変更、通常のデバッグ（作業の約 80%）。4.6 は販売継続 |
| アーキテクチャ / 大規模リファクタリング / オーケストレーション | Opus 5 | モジュール横断設計、大規模リファクタリング、多段タスクのオーケストレーション、難解な推論。4.8 は販売継続 |
| Codex 風コーディング | gpt-5.6-terra | Codex 風ワークフローのコード生成 |

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

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

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

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

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