Claude Codeのトークン節約 — 4つの操作のトレードオフ

Claude Codeのトークン消費を減らすには、次の4つの操作を組み合わせます。

• 起動時に積まれるコンテキストを絞る
• 重い処理をサブエージェントに逃がす
• プロンプトキャッシュを壊さない
• タスクの難易度でモデルとeffortを切り替える

ただしこの4つは単純な足し算になりません。一部は互いの効果を打ち消し合います。本稿で扱うのは、その相殺関係を踏まえた実践手順と、今日から試せる優先順位です。Claude Code自体の導入や基本機能全体はClaude Code(クロードコード)とは、プランの選び方やコスト試算はClaude Codeの料金の選び方にそれぞれ譲り、ここでは消費量そのものを減らす操作に絞ります。

まずClaude Codeの消費内訳を見る

節約を始める前に、自分が何にトークンを使っているかを確認すると効率的です。

/usage はプラン枠の消費内訳を、スキル・サブエージェント・プラグイン・MCPサーバーごとに表示します。画面には long context(長いコンテキストによる消費)や cache misses(キャッシュが効かなかった消費)の割合も出ます。直近使用量の10%以上を占める挙動には、削減のヒントが添えて表示される仕組みです。

/context では、いまのセッションで何がコンテキストを占めているかを内訳表示できます。/usage がプラン全体の傾向を見るのに対し、/context はセッション1本の中身を見る道具です。両方を併用すると、削るべき箇所の見当がつきやすくなります。

Claude Code起動時のコンテキストを削る

Claude Codeのトークンコストは、処理するコンテキストのサイズに比例します。会話が長くなるほど、無関係な話題が混ざるほど、以降のメッセージ1件あたりの単価が上がります。

最初の一手は、無関係な作業に切り替えるタイミングで /clear を使うことです。古いコンテキストが以降のメッセージすべてでトークンを消費し続ける事態を防げます。/clear の実行自体にコストはかかりません。

長い作業を複数のセッションに分けて進める場合は、/rename でセッションに分かりやすい名前を付けてから /clear し、必要になったら /resume で呼び戻す運用も使えます。区切りごとにコンテキストをリセットしながら、過去の作業には戻れる状態を保てます。

/compact は要約でコンテキストを圧縮しますが、既定のままだと何を残すかをClaude任せにします。/compact Focus on code samples and API usage のように指示を付けると、要約時に優先して残す内容を制御できます。新しいセッションで空振りすると Not enough messages to compact. と表示されます。

CLAUDE.mdにも同様の指示を書けます。

# Compact instructions
When you are using compact, please focus on test output and code changes

CLAUDE.md自体が肥大化するのもコストです。目安は200行以内で、手順の詳細はskillに移し、CLAUDE.mdには要点だけを残します。

Anthropic APIやサブスクリプション経由の既定では、MCPサーバーのツール定義はツール検索によって遅延読み込みされます。セッション開始時にコンテキストへ入るのはツール名だけで、実際に使うツールのスキーマは必要になった時点で読み込まれます。

この既定には例外があります。Google CloudのAgent Platformでは既定で無効です。ANTHROPIC_BASE_URL が非ファーストパーティのホストを指す構成でも無効になります。

前方に載せたい定義がある場合は ENABLE_TOOL_SEARCH=auto を明示します。指定したときだけ閾値方式に切り替わり、コンテキストウィンドウの10%に収まる分を起動時に読み込み、超過分は遅延読み込みのままです。割合は auto:5 のように auto:N でN%に変更できます。

ENABLE_TOOL_SEARCH=auto:5 claude

gh や aws のようなCLIツールが使えるなら、MCPサーバー経由より効率的です。ツール1つごとの定義がコンテキストに乗らないためです。

ログファイルを丸ごと読ませるのも無駄が大きい操作です。hookでエラー行だけに絞り込めば、数万トークンの読み込みを数百トークンまで圧縮できます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" }]
      }
    ]
  }
}

設定で参照する ~/.claude/hooks/filter-test-output.sh の中身は次の通りです。保存先のフォルダを mkdir -p ~/.claude/hooks で作り、保存後に chmod +x ~/.claude/hooks/filter-test-output.sh で実行権限を付けておきます(実行ビットがないとhookは何も言わずに素通りします)。

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered_cmd\"}}}"
else
  echo "{}"
fi

hookが実行結果を絞り込むのに対し、skillはドメイン知識を埋め込んで探索そのものを減らす手法です。たとえばcodebase-overviewのようなskillにリポジトリの構成やモジュール境界を書いておけば、Claudeは同じ情報を得るためにファイルを何度も読み込んで探索する必要がなくなります。処理をhookとskillの両方に逃がすことで、探索コストと出力コストの両方を削れます。

起動場所の選び方や読み込み除外設定、モノレポでのパッケージ境界の切り方は、大規模なコードベースに特有の話です。詳しくはClaude Codeのコンテキスト管理で構造面から扱っています。ここでは日々の運用習慣に絞ります。

サブエージェント委任は得とは限らない

サブエージェントは独自のコンテキストウィンドウを持つ、メイン会話から隔離された実行単位です。テスト実行やドキュメント取得、ログ処理のような冗長な出力を生むタスクを任せると、詳細な出力はサブエージェント側に留まり、メイン会話にはサマリーだけが返ります。

モデル指定には優先順位があります。

1. CLAUDE_CODE_SUBAGENT_MODEL 環境変数
2. 呼び出し単位の model パラメータ
3. サブエージェント定義の model frontmatter
4. メイン会話のモデル

frontmatterの model には sonnet opus haiku fable のほか、完全なモデルIDや inherit を指定できます。既定は inherit です。

組み込みのExploreエージェントは、v2.1.198以降、メイン会話のモデルを継承する挙動になりました(以前はHaiku固定でした。Claude API経由での利用ではOpusが上限です)。調査系タスクをHaiku相当のコストに抑えたい場合は、model: haiku を指定した独自のExploreサブエージェントを定義すると、組み込みの挙動を上書きできます。

ここで見落としやすいのが起動コストです。サブエージェントは親とは別に会話を開始し、独自のシステムプロンプトとツールセットで自分のキャッシュを一から構築します。初回呼び出しではキャッシュヒットが一切なく、キャッシュの有効期間もサブスクリプションの1時間ではなく常に5分です。軽いタスクを都度サブエージェントに投げると、この初期化コストが本体の節約分を上回ることがあります。

この起動コストを避ける手段もあります。会話をセッション内でそのまま分岐させる /subtask は、親のシステムプロンプト・ツール・会話履歴を引き継ぎます。最初のリクエストから親のキャッシュを読むため、ゼロからのキャッシュ構築が要りません。サブエージェントを都度立ち上げるコストが気になる場面では、subtaskでの分岐が有力な代替になります。似た名前の /fork は別機能です。既定のagent view構成では、セッション全体を独自予算の別バックグラウンドセッションへ複製するだけで、親キャッシュを読む用途には使えません。agent viewを無効にした構成でのみ、/fork がこのセッション内フォークとして動きます。

並列でリサーチさせる使い方も有効ですが、詳細な結果を返すサブエージェントを何本も同時に走らせると、個々のサマリーの合計がメイン会話を圧迫します。歯止めはあるものの、ultracode を有効にしたセッションでは効きません。並列化するタスクの数と、返す内容の粒度は分けて考える必要があります。作り方やパターンの詳細はClaude CodeのSub-agentsガイドを参照してください。

プロンプトキャッシュを壊さない立ち回り

Claude Codeのリクエストは、システムプロンプト・プロジェクトコンテキスト(CLAUDE.mdやauto memory)・会話履歴という3層構造で送られます。変更が起きにくい層を先頭に置くことで、共通の接頭辞をキャッシュから読み、変更があった分だけを新規処理する仕組みです。

一部の操作はこの接頭辞を丸ごと壊し、次のリクエストがキャッシュなしで全履歴を再処理する原因になります。

permission modeの切り替え自体はシステムプロンプトもツール定義も変えないため、ふだんはキャッシュに影響しません。例外は /model opusplan を設定している場合です。opusplanはplan modeへの出入りのたびにOpusとSonnetを切り替える設定なので、モード切替がそのままモデル切替になり、次のリクエストはキャッシュなしで全履歴を再処理します。plan modeを何度も往復するタスクでopusplanを使うと、切替のたびにこのコストが発生します。

fast modeを有効にするとリクエストヘッダーが追加され、それがキャッシュキーの一部になります。ただしキャッシュが壊れるのは会話あたり1回だけです。それ以降の同一会話内でのON/OFF切替はキャッシュを保ちます。なお非Opusモデルからのfast mode有効化は、モデル切替も同時に伴う操作です。fast modeの料金体系や有効化方法はfast modeガイドで扱っています。

キャッシュの有効期間(TTL)は、サブスクリプションでは自動的に1時間になり、1時間以内の中断ならキャッシュが残る仕組みです。APIキーや他のクラウドプロバイダー経由では既定で5分のままで、ENABLE_PROMPT_CACHING_1H=1 を設定すると1時間に延長できます。使用量上限を超えてusage creditsを使っている場合は、書き込み単価が高い1時間TTLではなく自動的に5分TTLに切り替わります。

/compact が最も高くつくのは、TTLを超えて久しぶりに再開したセッションです。キャッシュが残っていないため、要約リクエスト自体が全履歴を未キャッシュ入力として再処理します。/compact は作業中の自然な区切りだけで使うのが、キャッシュヒット率を保てる運用です。

会話を巻き戻したいだけなら、新しい接頭辞を作る /compact より、既にキャッシュ済みの接頭辞まで切り詰める /rewind のほうが安上がりです。

緩和策として、Pro / Maxプランにはサマリーからの再開という機能もあります。TTLを超えて中断した大きなセッションを再開するときにClaude Codeが提案し、使うと以降のリクエストで全履歴を運ぶ必要がなくなります。

キャッシュの効き具合は2つの指標で確認できます。cache_read_input_tokens はキャッシュから読んだ分で、通常の入力単価の約10%で課金されます。cache_creation_input_tokens は新規に書き込んだ分です。この2つの比率を見れば、キャッシュがどれだけ効いているかがわかります。仕組みの詳細はプロンプトキャッシュの仕組みで扱っています。

モデルとeffortを難易度別に切り替える

モデル選択の目安は明確です。Sonnetはほとんどのコーディングタスクを問題なくこなし、Opusより単価が低くなります。複雑なアーキテクチャ判断や多段階の推論が要るタスクだけOpusを予約し、/model でセッション途中でも切り替え可能です。単純なサブエージェントタスクには model: haiku を指定します。

複雑なタスクに取りかかる前に、Shift+Tabでplan modeへ切り替えて方針を固める運用も、結果的にトークンの節約になります。方向性を誤ったまま実装を進めると、後からの手戻りのほうが高くつくためです。設計と実行でモデルを使い分けたいときは、/model opusplan を使うとplan modeではOpus、実行ではSonnetに自動で切り替わります。ただし前節で触れた通り、この切り替えはモデル切替そのものです。plan modeを何度も往復するタスクでは、切替のたびにキャッシュがゼロに戻るコストが節約分を打ち消すことがあります。

方向がずれたと気づいた時点で早めに止めるのも、同じ理由で効きます。Escapeキーで処理をすぐに止め、/rewind を使うかEscapeを2回押せば、直前のチェックポイントまで会話とコードを戻せる仕組みです。誤った方向のまま生成を続けてから直すより、早い段階で軌道修正するほうが、手戻りにかかるトークンを抑えられます。

effortレベルはコストと能力のトレードオフを直接動かすパラメータです。

effortの切り替えは、次のいずれからでもできます。

• /effort コマンド
• /model 内の矢印キー
• --effort フラグ
• CLAUDE_CODE_EFFORT_LEVEL 環境変数
• settingsの effortLevel キー
• skillやサブエージェントのfrontmatterの effort フィールド

/effort メニューにはlow〜maxのほかに ultracode という項目もあります。これはモデルのeffortではなく、Claude Code側の設定です。xhighのeffortを送りながら動的にワークフローを組ませる、セッション限定の挙動です。settingsの effortLevel キーが受け付けるのはlow / medium / high / xhighのみで、max と ultracode はsettingsに書けません。

ほとんどのタスクでは、モデルの既定effortをそのまま使うのが基本です。

extended thinkingは既定で有効です。thinkingトークンは出力トークンとして課金され、既定の予算は1リクエストあたり数万トークンに達することもあります。節約の選択肢はeffortを下げる、/config でextended thinkingを無効にする、固定の思考予算を持つモデルでは MAX_THINKING_TOKENS 環境変数で予算を下げる、の3つです(例: 8000)。ただしFable 5は常時extended thinkingで動作するため、/config からは無効にできません。

ルーチンワーク、つまり正確に指示できる編集はSonnetで十分です。一方、微妙なバグや不慣れな領域、アーキテクチャ判断のような複雑なタスクでは、大きいモデルのほうが有利です。少ない試行回数で同じ品質に到達し、合計コストが下がる場合があります。この関係をタスクの種類で表にすると次のようになります。

なお既定モデルはアカウント種別で分かれます。

後者では /model でSonnetを選ぶこと自体が節約になります。

1Mコンテキストウィンドウは、200Kを超えたトークンにも単価の割増がかかりません。ただし利用条件は製品ごとに異なります。Max / Team(Standard・Premiumとも)/ Enterpriseでは、Opusが自動的に1Mへ引き上げられます。一方Sonnet 4.6の1Mは、Maxを含む全サブスクリプションでusage credits経由の利用です。大きいコンテキストを恐れて過剰に /clear する必要はなく、節約の主役はキャッシュヒット率とモデル選択です。

Claude Codeの4つの操作は足し算にならない

ここまでの4つの操作は独立ではありません。組み合わせ方を間違えると、片方の節約分をもう片方が食いつぶします。

原因は共通しています。キャッシュもサブエージェントも、「一度作った状態を使い回す」ことで安くなる仕組みです。状態を切り替える操作(モデル・effort・要約)を頻繁に行うほど、隔離のメリット(サブエージェント・agent teams)が薄れます。セッション冒頭でモデルとeffortを決め切り、途中の切り替えを最小限にするのが、この4つを共倒れさせない一番簡単な方法です。

よくあるつまずき

あいまいな指示は探索コストを増やします。「このコードベースを改善して」のような依頼はスキャン範囲が広がり、読み込むファイル数が膨らむのが実態です。「auth.tsのログイン関数に入力検証を追加して」のように対象を絞ると、最小限のファイル読み込みで済みます。

複雑なタスクでは、検証条件を先にプロンプトへ含めておくと手戻りが減ります。期待する出力やテストケースを添えておけば、Claudeは自分の出力を検証してから返し、修正の往復そのものが減ります。ファイルを1つ書いて動作を確認し、それから次に進むという小刻みな進め方も同じ理由で有効です。問題が小さいうちに見つかるほど、直すコストは低く済みます。

型付き言語のプロジェクトでは、code intelligenceプラグインも探索コストを抑えます。grepや複数ファイルの読み込みが必要な場面を、「定義へ移動」のような1回の操作に置き換えられることがあります。

バックグラウンドで動くプロセスも完全に無料ではありません。セッションあたり1回0.04ドル未満とわずかですが、待機中のスケジュールタスクは毎回フルコンテキストを送信するため、放置したまま多用すると積み上がります。

MCPサーバーの定義はツール検索で遅延読み込みされるため、サーバーの数はコンテキストにほぼ影響しません。効いてくるのは実行結果のほうで、既定では1回あたり25,000トークンまで許容されます。ログのようなツールが大量出力を返す構成では、MAX_MCP_OUTPUT_TOKENS の既定値を疑ってみる価値があります。使っていないサーバーが残っている場合は、/mcp で設定済みサーバーを一覧し、使っていないものを無効化しておくのも有効です。

よくある質問

サブエージェントを並列で走らせすぎないための上限はありますか

上限はあります。同時実行数の既定は20本、セッション全体での起動数の既定は200件で、それぞれ CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS と CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION で調整できます。ただし ultracode を有効にしたセッションは同時実行数の上限が適用されません。既定値を上げる場面は稀で、メイン会話の圧迫を防ぐガードレールとして機能させておくのが無難です。

チームで使うとき1人あたりの消費をどう抑えますか

個人と同じく、モデル選択とキャッシュヒット率がそのまま効きます。加えてteammateごとに独立したコンテキストウィンドウを持つ点がチーム特有の論点です。人数分のコンテキストがそのまま積み上がるうえ、plan modeで動くteammateがいる構成はコストがさらに膨らみます。日常タスクの多いteammateには、既定モデルに頼らず /model でSonnetを明示指定しておくと消費を抑えられます。

Bedrock / Google CloudのAgent Platform経由ではキャッシュTTLは何分ですか

既定は5分です。自動的に1時間TTLになるのはサブスクリプション経由の利用で、usage creditsを使っている場合は5分に戻ります。BedrockやGoogle CloudのAgent Platform(旧Vertex AI)経由の利用は、APIキー直接利用と同様にキャッシュTTLの既定が5分になります。1時間に延ばしたい場合は ENABLE_PROMPT_CACHING_1H=1 を設定します。

/clearと/compactはどちらを先に検討すべきですか

作業の対象が完全に変わるなら、/clearが候補になります。コストはかからず、キャッシュへの影響も考えずに済みます。同じ作業の続きで文脈だけを圧縮したいときは /compact を使うのが基本の使い分けです。

effortを下げると何が犠牲になりますか

低いeffortは知的難度を求めない作業向けで、多少の精度低下と引き換えにトークン消費を抑えます。微妙なバグの特定やアーキテクチャ判断のようなタスクでeffortを下げると、試行回数が増えて合計コストがかえって上がることも珍しくありません。難易度に見合わない下げすぎは、節約ではなく手戻りに変わります。

まとめ

優先順位をつけるなら、コストゼロで即実行できる順からです。

• 無関係な作業に切り替えるときの /clear
• セッション冒頭でのモデルとeffortの確定
• テスト実行やログ処理のサブエージェント委任
• カスタム指示付きの /compact を自然な区切りだけに使う

この4つから始めると相殺が起きにくくなります。削減できる量は環境によって差が大きく、「何%減った」という統一的な数値は公表されていません。まず /usage で自分の消費内訳を見てから、効く操作を足していくのが現実的です。