Claude Code は本当に便利なツールだ。そして使い方を間違えると、本当に高くつく。
Max プランで数日間ヘビーに使うぶんには許容範囲に収まることも多い。ただ同じワークフローがチーム規模に拡大したり、CI パイプライン上で走り続けたりすると、月末に誰も予想しなかったような請求書が届くことになる。
朗報がある。Claude Code のコスト問題のほとんどは、予算の問題ではなくワークフローの問題として解決できる。トークンの無駄遣いは、いくつかのよく知られたパターンに起因することが多い。膨れ上がった CLAUDE.md、不必要なファイル読み込み、冗長なコンテキスト、タスクに見合わないモデル選択、これらを修正するだけで、アウトプットの質を落とさずにコストを大幅に削減できる。
このガイドでは、インパクトの大きい順に実践的なテクニックを解説する。
トークンはどこに消えているのか
最適化の前に、何に対して課金されているかを把握しておく必要がある。
Claude Code はトークン単位で課金される。インプットトークン（送信する内容、つまり会話履歴・読み込んだファイル・ツール出力）とアウトプットトークン（Claude が返す内容）だ。一般的にインプットの方が安いが、実際の Claude Code セッションでは、ほぼ必ずインプットが支配的になる。
典型的なセッションの内訳を見てみよう。
CLAUDE.md はコンパクションのたびに読み込まれる。 CLAUDE.md が 3,000 トークンある場合、セッション開始時に 3,000 トークンを消費する。そして /compact を実行するたびに同じことが起きる。3 回コンパクションがある長いセッションでは、1 行もコードを書かない段階で 12,000 トークンが消えることになる。
ツール出力はあっという間に積み上がる。 bash コマンドの実行結果、ファイル読み込み、glob 検索のすべてがコンテキストに追加される。大規模なコードベースへの grep -r は何千行もの結果を返すことがある。失敗したテストスイートは全出力をダンプする。これらの数字は侮れない。
ファイル読み込みは全文コピーと同じだ。 Claude Code がファイルを読み込むと、そのファイル全体がコンテキストウィンドウに入る。セッション冒頭に「コードベースを理解するため」として 5 つの大きなファイルを読ませると、何も始める前に 20,000〜50,000 のインプットトークンを消費してしまう可能性がある。
会話履歴は線形に増加する。 自分のメッセージ、Claude の応答、やりとりの往復、これらはセッション全体を通して蓄積され続ける。メッセージが 60 件を超えるような長い会話では、履歴だけで数万トークンになることもある。
この内訳を理解すれば、どこに介入すべきかが見えてくる。最もレバレッジが効くのは、自動的に読み込まれるものを削減すること、読み込むファイルを絞り込むこと、そしてタスクに応じて適切なモデルを選ぶことだ。
モデル選択：最大のコスト削減レバー
すべてのタスクに Opus を使う必要はない。間違ったモデルを使い続けることが、不必要なコストの最大の原因になっている。
Opus 4.6: 複雑な推論、アーキテクチャ上の意思決定、複数ファイルにまたがる難しいデバッグ、文脈的な判断が必要なコードレビューに使う。高コストのモデルなので、意識的に使い所を選ぶべきだ。
Sonnet 4.5/4.6: 日常的なコーディングタスクのほとんどはこれで十分だ。仕様が決まった機能の実装、定義済みの基準へのリファクタリング、既存コードのテスト追加など。品質は十分で、コストは大幅に低い。
Haiku（プランで利用可能な場合）: 繰り返しの多いタスク、要約、変更内容がすでに明確になっているシンプルな編集に適している。
実際の問題は、Claude Code がすべてに対して同じモデルをデフォルトで使うことだ。解決策は、リクエストを明示的に伝えること、そしてチームが API 経由で Claude Code を使っている場合はタスクの種類ごとにモデル設定を行うことだ。
CLAUDE.md に次のような指示を書いておくと、特定のカテゴリには軽量なモデルを使うよう誘導できる。
## モデルの使い分け
以下のタスクでは、利用可能であれば効率の良いモデルを使用してよい:
- 繰り返しのボイラープレート生成（例：20 個のファイルに同じインターフェースを追加する）
- コンテキスト用のファイル内容の要約
- シンプルな変数名変更やフォーマット修正
以下は必ずフルの推論能力を使うこと:
- アーキテクチャの変更
- バグの根本原因分析
- セキュリティ上の変更
- データベーススキーマや API コントラクトの変更これがモデルを直接制御するわけではないが（それはクライアントの設定による）、意図を示す役割を果たし、マルチエージェント設定で Claude Code が自律的な判断を行う際に機能する。
プロンプトキャッシュ：使っていない可能性が高い無料の最適化
Anthropic はプロンプトキャッシュをサポートしており、Claude Code は一部のコンテンツに対して自動的にこれを活用する。ただし、仕組みを理解しておくことでキャッシュヒット率を最大化するワークフロー設計が可能になる。
プロンプトキャッシュの仕組みはシンプルだ。プロンプトコンテキストの冒頭部分が以前のリクエストと完全に一致する場合、Anthropic はそのキャッシュ済み部分を割引価格で提供できる。2026 年初頭時点では、キャッシュ読み込みのコストは標準インプットトークン価格の約 10% だ。
Claude Code にとってこれが意味するのは、CLAUDE.md のコンテンツはセッション開始時とコンパクション後に毎回読み込まれるため、内容が安定していればキャッシュの強力な候補になるということだ。CLAUDE.md の 1 文字でも変わると、その部分以降のキャッシュが無効になる。
実践的な注意点:
CLAUDE.md の安定した部分を先頭に置く。変化しない情報（技術スタック・コア規約・プロジェクト構造）は、頻繁に変わる情報（進行中のタスクメモ・最近の決定事項）より前に書く。キャッシュの無効化は前方に伝播するため、10 行目を変更すると 10 行目以降のキャッシュが全部無効になる。
変化する内容と安定した内容を分離する。CLAUDE.md は永続的なコンテキスト用に使い、セッション固有のメモは別の CURRENT_CONTEXT.md（または類似のファイル）に書いて、毎セッションではなく必要なときだけ明示的に読み込む形にすることを検討しよう。
CLAUDE.md にタイムスタンプや自動生成コンテンツを入れない。ファイル先頭のタイムスタンプは毎回キャッシュ全体を無効にする。
複数のエンジニアが同じ CLAUDE.md を使うチーム設定では、安定した共有コンテンツを持つことで大きなキャッシュ節約が生まれる。2,000 トークンの CLAUDE.md を 10 名のエンジニアが 1 日 50 回使うと、1 日に 100 万トークンになる。10% コストのキャッシュヒットが発生すれば、その部分だけで 10 倍のコスト削減になる。
スリムな CLAUDE.md の設計
コストを監査してきた開発者たちが口を揃えて言う最もよくある指摘がある。「あなたの CLAUDE.md、必要以上に大きいですよ」というものだ。
よくある肥大化のパターンを見ていこう。
Claude がすでに知っていることの説明。 React の仕組み、TypeScript インターフェースの使い方、REST の意味、これらは書く必要がない。Claude Code はこれらを知っている。CLAUDE.md にはコードベースから推測できない情報を書くべきだ。あなた固有の規約・設計判断・制約がそれにあたる。
コードの中にある情報の重複。 package.json が pnpm を使っていることを示しているなら、CLAUDE.md に「pnpm を使っています」と書く必要はない。ディレクトリ構造が自明であれば、散文で説明しなくていい。
古くなったコンテンツ。 3 ヶ月前のタスクリスト、削除したライブラリへの参照、当時のメモ。これらは毎セッションにトークンを消費しつつ、むしろ有害な情報（積極的に誤解を招く可能性がある）を提供する。
短いルールで事足りる場合の冗長な例。 関数の正しい書き方を示す 200 トークンの例の代わりに「関数は型付きオブジェクトを返すこと。any は禁止。正規の例は src/utils/user.ts を参照」と書く。これで実際の例を示しつつ、CLAUDE.md にコピーせずに済む。
典型的なプロジェクトのスリムな CLAUDE.md は 500〜1,500 トークンが目安だ。3,000 トークンを超えているなら、1 行ずつ監査しよう。詳細なアプローチは CLAUDE.md トークンバジェット最適化ガイド を参照してほしい。
@import ディレクティブも知っておく価値がある。すべてのルールをインラインに書く代わりに、CLAUDE.md をセクションに分割して条件付きでインポートできる。フロントエンド作業中にバックエンドのルールを読み込まないようにする、といった使い方が可能だ。具体的な方法は トークン最適化詳解 で説明している。
.claudeignore：読む必要のないファイルにコストをかけない
.claudeignore は .gitignore の Claude Code 版だ。ここに記載されたファイルやディレクトリは Claude Code のプロジェクトビューから除外される。
デフォルトでは、Claude Code はプロジェクト内のすべてのファイルにアクセスして読み込むことができる。大規模なモノレポでは、生成ファイル、テストフィクスチャ、なぜかコミットされてしまった依存関係ディレクトリまで含まれる。Claude がプロジェクト全体の glob や検索を実行すると、それらすべてをトラバースする。
ほとんどのプロジェクトで実用的な .claudeignore は次のようになる。
# 依存関係
node_modules/
vendor/
.venv/
__pycache__/
# ビルド出力
dist/
build/
out/
.next/
.nuxt/
# 生成ファイル
*.generated.ts
*.generated.py
coverage/
.nyc_output/
# 大きなバイナリファイルやデータファイル
*.csv
*.json.gz
*.parquet
*.db
*.sqlite
# ロックファイル（Claude が読む必要はない）
package-lock.json
yarn.lock
pnpm-lock.yaml
poetry.lock
# 内部ツールのログ
logs/
*.logコストへの影響は地味だが確実だ。Claude Code が検索ツールを使ってコードベースを探索するとき、.claudeignore が許可した範囲しか検索しない。node_modules を除外するだけで、ファイルシステム操作のスコープが劇的に縮小できる。
さらに精度を高めたい場合は、プロジェクト固有のディレクトリも追加しよう。Claude が読む必要のないテスト用 JSON ファイルが 500 件入った data/fixtures/ があれば除外する。Claude Code に変更させるべきでない自動生成ドキュメントも除外する。
ファイル読み込みの最適化：必要なものだけを読む
日常的な Claude Code の使い方で最もコストが高いパターンの一つは、具体的なタスクを渡す前にコードベース全体の理解を求めることだ。
「作業を始める前に src/api/ ディレクトリ全体を読んで構造を理解してください」
一見合理的に思えるが、高コストだ。40 ファイル × 平均 200 行の api/ ディレクトリを読むと、何も始まる前に 8,000 行のコードがコンテキストウィンドウに入る。
より良いアプローチは、タスクを渡して Claude に必要なものを引き出させることだ。Claude Code にはファイル読み込みツールが備わっており、それがまさにそのためにある。バグや機能を説明すれば、Claude は関連するファイルを自分で読む。事前にコードベース全体を読ませるツアーは必要ない。
どうしても全体像の把握が必要なら、最も情報密度の高いソースに誘導しよう。
作業開始前に ARCHITECTURE.md と README を読んでください。
個別のソースファイルは、特定のタスクに必要な場合にのみ読んでください。2 ファイルの把握（ARCHITECTURE.md + README）なら 1,000 トークン程度で済む。「api/ ディレクトリ全体を読む」は 50,000 トークン以上になる。タスクの結果は多くの場合、大差ない。
同じ理由から、「X をリファクタリングして」と頼む代わりに、特定の変更を明確に指定することを好む習慣をつけよう。明確な変更は読むファイル数が少なくて済む。「X をリファクタリングして」と言うと、X が触れているすべて、X に触れているすべてを読みに行く招待状になる。
長期作業のための Git Worktree パターン
複数のセッションにまたがる複雑なフィーチャー開発では、git worktree がコスト管理において一見すぐにはわからない利点を持っている。
worktree なしの場合、新しいセッションは毎回ゼロから始まる。Claude は前のセッションで何をしたかを再構築する必要がある。多くのファイルを再度読むか、詳細なセッションメモを書かなければならない。
worktree ありの場合、フィーチャーごとに専用の worktree を用意し、そのフィーチャーに関連するコンテキストだけを含むフィーチャー固有の CLAUDE.md オーバーライドを置ける。その worktree でのコンテキストは集中している。単独のフィーチャーに取り組む際にコードベース全体のコンテキストを読み込まずに済む。
詳細は git worktree ガイド で扱っているが、コストに関連するパターンはこうだ。
# フィーチャー用 worktree を作成する
git worktree add ../feature-payment-refactor -b payment-refactor
# worktree ローカルの CLAUDE.md を追加する
cat > ../feature-payment-refactor/CLAUDE.md << 'EOF'
# 支払い処理リファクタリング コンテキスト
## 目標
支払い処理を Stripe v2 から Stripe v3 SDK に移行する。
## 関連ファイル
- src/payments/（主要スコープ）
- src/api/checkout.ts
- tests/payments/
## 触らないこと
- src/auth/（別スコープ）
- src/admin/（別スコープ）
## 進捗
- [x] StripeClient の初期化を更新
- [x] Webhook 処理を移行
- [ ] チェックアウトセッション作成を移行
- [ ] エラーハンドリングを v3 フォーマットに更新
EOFこの CLAUDE.md は 200 トークンで、タスクに完全に集中している。このディレクトリには独自の CLAUDE.md があるため、メインプロジェクトの CLAUDE.md は読み込まれない。Claude Code は認証システムの話も、CRM 連携の話も、メインの CLAUDE.md にある他のことを知る必要がない。
原則はシンプルだ。コンテキストをタスクのスコープに絞る。フィーチャー固有のコンテキストは、プロジェクト全体のコンテキストより安く、多くの場合より効果的だ。
並列処理のためのサブエージェントパターン
--agent フラグやマルチエージェントワークフローを使っている場合、コンテキストのアーキテクチャがコストに直接影響する。
高コストなパターン: 全コンテキストを蓄積するメインエージェントがサブエージェントを生成し、サブエージェントが詳細な要約を返してメインコンテキストに注入する。
効率的なパターン: 境界が明確で定義済みのタスクをこなし、最小限の構造化された出力を返すサブエージェントを使う。
詳細なサブエージェント出力（高コスト）:
メインエージェント: "src/api/ の各ファイルを見て、見つけたことを報告してください"
サブエージェント: 全ファイルの詳細分析として 2,000 トークンを返す
→ メインエージェントのコンテキストが 2,000 トークン増加絞り込まれたサブエージェント出力（効率的）:
メインエージェント: "src/api/ の中に deprecated-utils.ts をインポートしているファイルがあるか確認してください。ファイル名のリストだけ返してください"
サブエージェント: ["src/api/user.ts", "src/api/checkout.ts"] を返す
→ メインエージェントのコンテキストが約 20 トークン増加タスクの仕様がサブエージェントの読み込み量・処理量・返却量を決める。精密なタスク定義は探索的なものより安い。
サブエージェントアーキテクチャの詳細については サブエージェントベストプラクティスガイド を参照してほしい。
セッション長とコンパクション戦略
長いセッションはコンテキストが増えてコストが上がる。これは当たり前だ。わかりにくいのは、コンパクション自体がタダではないということだ。
Claude Code が /compact を実行すると、現在のセッションの要約を生成し、その要約を新しいコンテキストとして再開する。要約の生成自体にトークンがかかる。そして CLAUDE.md が大きければ、コンパクション後にフル価格で再読み込みされる。
セッションコストを管理する戦略を見ていこう。
より短く、集中したセッションで作業する。 特定のタスクへの 30 分のセッションは、2 時間の探索的セッションより安い。常に実践できるわけではないが、デフォルトとして意識する価値がある。
自然な切れ目でコンパクションする。 コンテキストが満杯になって強制的にコンパクションする前に、自然な区切り点（フィーチャーの完了、テストパスの終了）で手動コンパクションする。きれいな区切りでのコンパクションはより良い要約を生成し、次のセッションが高品質なコンテキストで始まれることを意味する。
メッセージでコンテキストを繰り返す代わりに CURRENT_TASK.md を使う。 セッション開始時に Claude を再オリエンテーションする必要がある場合は、コンテキストをファイルに書いて一度参照するだけにする。
作業を始める前に CURRENT_TASK.md を読んでください。これは長いメッセージでコンテキストを書き出すより安く、再入力なしにセッションをまたいで再利用できる。
チームと CI の設定
個々の開発者の習慣は、チーム規模で使う場合のデフォルト設定に比べると影響が小さい。
CI/CD パイプライン: Claude Code が実際に何を読んでいるか監査する。集中したタスクを実行する前にリポジトリ全体を読む CI ジョブは不必要にコストを燃やしている。.claudeignore でスコープを制限し、CI が扱うタスク用に CI 固有の CLAUDE.md オーバーライドを書く。
共有コードベース: CLAUDE.md を集約する。CLAUDE.md がエンジニアごとにバラバラな場合、キャッシュの恩恵を受けられない。全チームメンバーが使う安定した共有 CLAUDE.md は大きなキャッシュ節約を生む。
使用状況の可視化: チームが個別サブスクリプションではなく API 経由で Claude Code を使っている場合、使用状況を計測する。セッションあたりのトークン、開発者あたりのトークン、タスクタイプあたりのトークンを追跡する。見えないものは最適化できない。Anthropic API はすべてのレスポンスでトークン使用量を返すので、それをログに記録する。
レート制限: CI やバックグラウンドジョブで自律エージェントを実行する場合、明示的なレート制限またはセッショントークンバジェットを設定する。予期しないループに入ったエージェントは、誰も気づかないうちに大量のトークンを消費することがある。
実践的な監査：最大のコスト要因を特定する
自分の具体的なコスト問題を素早く特定したい場合は、次のプロセスに従う。
-
セッションにロギングを追加する。 いくつかの実際のセッションで
CLAUDE_DEBUG=1（または同等のもの）を有効にして Claude Code を実行する。ログを確認して、どの操作が最も大きなツール出力を生成したか確認する。 -
CLAUDE.md のサイズを測定する。
wc -w CLAUDE.mdで語数を取得する。1.3 倍するとトークン数の概算になる。2,000 トークンを超えていたら 1 行ずつ監査する。 -
.claudeignore のカバレッジを確認する。 プロジェクトルートで
find . -not -path './.git/*' | wc -lを実行する。数千以上返ってきて.claudeignoreがない場合、無駄なファイルシステムトラバースが発生している可能性が高い。 -
最も頻繁に送るプロンプトを見直す。 1 日に何十回も送るプロンプトは最適化する価値がある。1 日 50 回送るプロンプトを 100 トークン削減すると、開発者一人あたり 1 日 5,000 トークンの節約になる。
-
サブエージェントの戻り値サイズを確認する。 サブエージェントを使っている場合、実際に何を返しているか確認する。メインコンテキストに注入される詳細な戻り値はよくあるコスト漏れだ。
トレードオフ：コストと thoroughness のバランス
ここには正直に向き合う必要のある真のテンションがある。上記のコスト最適化のいくつか、読むファイルを減らすこと、CLAUDE.md を短くすること、セッションを短くすること、これらは Claude Code のコードベース理解を低下させる可能性がある。その理解の低下が品質低下につながることもある。ミスが増え、修正の往復が増え、手直しが増える。
最適化の正しいターゲットは「セッションあたりのコスト」ではなく「動くアウトプット 1 件あたりのコスト」だ。少し長めの CLAUDE.md が 3 回の修正サイクルを要しない最初の一発目のコードを生み出すなら、そのトークン増加は全体的に安くつくかもしれない。
実践的なテスト方法はこうだ。一度に一つのことを最適化して、アウトプットの品質が変わるかどうか観察する。変わらなければ、その最適化は安全だった。変わったなら、その品質低下を許容できるかどうか判断する。
実際のところ、ほとんどのチームは最初の 20〜30% のコスト削減が品質低下なしに達成できることに気づく。CLAUDE.md の肥大化、不必要なファイル読み込み、日常タスクへの誤ったモデル選択、これらは純粋な非効率だ。対処は簡単だ。
より難しい最適化、つまり複雑なタスクのコンテキスト削減や連続性が有効な作業のセッション短縮は、判断が必要だ。仮定ではなくデータに基づいて判断してほしい。
コンテキスト管理の詳細については Claude Code コンテキスト管理ガイド を参照してほしい。CLAUDE.md 側については トークンバジェット最適化ガイド がプロンプト構造についてより深く掘り下げている。並列エージェントを実行するチームには サブエージェントベストプラクティスガイド がマルチエージェント設定のコストアーキテクチャをカバーしている。