Claude Codeがプロンプトの前に33kトークンを送信する理由と対処法

Claude Codeのトークン使用量に含まれるオーバーヘッドを理解する

エージェント型コーディングツールは、プロンプトを受け取る前にコンテキストを読み込みます。モデルには、自分の役割、呼び出せるツール、動作する環境を把握させる必要があります。Claude Codeは、この点では比較的重い部類に入ります。コールドスタート時の事前コンテキストは通常、およそ 33kトークン になります。一方、OpenCodeのような最小構成の代替ツールでは、報告される値はおよそ 7k.

この差は確かに存在しますが、品質の優劣を示すものではありません。設計上の選択です。33kによって、豊富な組み込みツールと、より信頼性の高いエージェント動作が得られます。7kでは、コンテキストを小さく抑え、コールドスタートのコストを下げられます。どちらかが「正解」というわけではなく、機能とコストの曲線上で異なる位置にあるのです。

Claude Codeの起動時トークンが何に使われるか、おおまかな内訳を示します。正確な数値はバージョンによって変わるため、固定値ではなく比率として捉えてください。

ほぼ常に、最も大きな割合を占めるのは ツール定義です。システムプロンプトが大半を占めると思っていた人には、意外な結果でしょう。

ツールスキーマがこれほど重い理由

モデルが呼び出せる各ツールは、名前、説明、パラメーターの完全なJSON Schemaを含む構造化スキーマとして渡されます。ネストしたパラメーターの説明や列挙値まで含めると、説明が充実したツールは単体でも500〜1,500トークンに達することがあります。Claude Codeは、ファイルの読み書き、編集、bash、glob、grep、ウェブ取得、タスクやエージェントの起動、ToDo管理など、幅広いツールを標準で有効にしており、そのすべてが毎回のリクエストに含まれます。

あるツールのスキーマを簡略化すると、おおよそ次のようになります。

{
  "name": "edit_file",
  "description": "Make a targeted edit to an existing file. Use this instead of rewriting the whole file when possible...",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "Absolute path to the file" },
      "old_string": { "type": "string", "description": "Exact text to replace, including surrounding context for uniqueness" },
      "new_string": { "type": "string", "description": "Replacement text" }
    },
    "required": ["path", "old_string", "new_string"]
  }
}

これを十数個以上のツール分に増やし、さらに接続したMCPサーバーが公開するすべてのツールを加えると、スキーマのペイロードは急速に膨らみます。よくある落とし穴は、「試してみるため」にMCPサーバーを三つインストールし、それぞれが8〜15個のツールを公開しているために、基本のトークン数が10kトークン増え、その後はその増加を意識しなくなることです。

頼んでいない環境コンテキスト

Claude Codeはリポジトリ内で起動すると、エージェントが基本的な質問のためにやり取りを費やさずに済むよう、状況を把握するための情報を注入します。具体的には、次のようなものが含まれます。

Working directory: /home/ryan/projects/api-gateway
Platform: linux
Git branch: feature/rate-limiting
Git status: 4 modified, 1 untracked
Recent commits: ...

これは実際に役立ちます。エージェントが最初から、作業中のブランチが機能開発用のブランチだと把握しているのも、このためです。ただし、やはりトークンは消費します。大規模なモノレポでは、ディレクトリのスナップショットが無視できない量になることもあります。

オーバーヘッドで実際に得られるもの

このオーバーヘッドを削減する前に、トレードオフを正しく捉えましょう。Claude Codeが最初の応答から、適切な周辺コンテキストを踏まえて正しいファイルを編集し、テストを実行し、並列タスク用のサブエージェントを起動し、プロジェクトの規約に従えるのは、この33kがあるからです。確認の質問を挟む必要もありません。7kトークンのエージェントは、多くの場合、そのコンテキストを 追加のやり取りで獲得する 必要があります。その結果、リクエスト数と遅延が増え、セッション全体では総トークン数まで増えることがあります。

したがって、比較すべきなのは「33kは無駄で、7kは効率的」ということではありません。比較すべき点は次のとおりです。

• 回数は少ないが、大きいリクエスト （Claude Code）対 回数は多いが、小さいリクエスト （最小構成のエージェント）
• すぐに使える機能 対 必要に応じて揃える機能
• セッションあたりの固定コストが高い 対 タスクあたりの変動コストが高い

五回のメッセージで進めるデバッグセッションなら、固定オーバーヘッドは十分に分散されます。一行だけ送って終わる用途では、無駄に感じられます。どちらの感覚も、その状況では正しいのです。

実際に自分で調整できるポイント

Claude Codeの基本ツールセットを書き換えることはできませんが、基本のトークン数を大きく変えられる調整ポイントが三つあります。

1. CLAUDE.mdを徹底的に削る

CLAUDE.md は、毎回のリクエストに全文が注入されます。事前コンテキストの中で100%自分で管理できる唯一の部分であり、私が最も多くの無駄を目にする場所でもあります。モデルが標準で従う理想的なスタイルガイドで埋まった、4kトークンものファイルがその例です。

簡潔にし、動作に不可欠な内容だけを残しましょう。次のような内容を優先します。

# Project: api-gateway

- Package manager: pnpm (never npm)
- Tests: `pnpm test` — must pass before any commit
- Do NOT edit files in /generated
- API errors use the AppError class in src/errors.ts

モデルが指示されなくても行うこと（「きれいなコードを書く」「コメントを追加する」など）は削除しましょう。目安として、ある行を削除してもエージェントの動作が変わらないなら、その行は無駄にトークンを消費しています。詳しいコンテキストは、メモリに貼り付ける代わりに、エージェントが参照できるファイルに置き、 必要に応じて 読み込ませましょう。

2. 使っていないMCPサーバーとツールを無効にする

多くの人にとって、これが最も効果の大きい対策です。実際に何が接続されているかを確認しましょう。

claude mcp list

何か月も前に追加したまま使っていないサーバーがあれば、削除しましょう。

claude mcp remove some-unused-server

許可するツールの範囲を絞り、スキーマをコンテキストに含めないようにすることもできます。プロジェクト設定またはユーザー設定で、次のように指定します。

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash", "Grep", "Glob"],
    "deny": ["WebFetch"]
  }
}

使用対象から外したツールの分だけ、毎回のやり取りでスキーマを送信するコストを削減できます。実際、私の場合は、情報量の多いMCPサーバーを一つ無効にしただけで、どのプロンプト調整よりも多くのトークンを節約できました。

3. プロンプトキャッシュを積極的に活用する

これが最も大きなポイントで、コスト計算全体を変えます。システムプロンプト、ツール定義、変化しないプロジェクトコンテキストは、 同じセッション内のすべてのリクエストで共通です 。そのため、プロンプトキャッシュに最適です。キャッシュ済みの入力トークンは新規の入力トークンより大幅に安いため、33kの事前コンテキストは、最初の呼び出し以降、ほとんど問題にならなくなります。

Claude Codeは自動でキャッシュを利用しますが、コンテキストの固定部分を実際に変えないようにすると、その効果を高められます。

• 書き換えを避けましょう： CLAUDE.md セッションの途中で変更すると、その位置より後のキャッシュが無効になります。
• 固定コンテキストは先頭に配置し、変わりやすい詳細は事前コンテキストではなくメッセージに入れましょう。
• 順序が重要です。キャッシュはプレフィックスに対して機能するため、先頭に近い部分を変更すると、それ以降がすべて無効になります。

実用上のポイントは、コストを抑えるために、 最初の リクエストのトークン数を最適化しつつ、キャッシュヒットを増やすために、 セッション 全体を最適化することです。安定してキャッシュされる33kのプレフィックスは、毎回作り直されてキャッシュされない7kのプレフィックスよりも、実際の作業セッション全体では安くなることがよくあります。

エージェント型のワークロードを大量に実行し、トークン単位のコストを細かく見ている場合は、AI Prime TechがClaudeモデル向けに提供しているような低価格のAPIアクセスを適切なキャッシュ運用と組み合わせることで、効果をさらに高められます。

実践上の要点

• 約33kの起動コストの大半は、システムプロンプトではなくツールスキーマです。 ツール定義とMCPサーバーがトークン使用量の大半を占めます。
• 無駄ではなく、トレードオフです。 オーバーヘッドによって、すぐに使える機能と、少ないやり取りでの作業が実現します。軽量なエージェントでは、コストが固定費から変動費へ移ります。
• まずMCPサーバーを点検しましょう。 使っていないサーバーの削除と、使っていないツールの禁止が、最も効果の大きい削減策です。
• CLAUDE.mdには動作に不可欠な内容だけを残しましょう。 モデルが標準で行うことは削除し、詳しいドキュメントは貼り付けずに、必要に応じて参照させましょう。
• 最初のリクエストを小さくするだけでなく、キャッシュヒットを増やす設計にしましょう。 安定してキャッシュされる事前コンテキストは、毎回作り直される小さなものより有利です。
• メッセージ単位ではなく、セッション単位で測定しましょう。 固定コストが分散されるタスク全体を基準に、オーバーヘッドを評価しましょう。