0:00 0:00
Article
Claude Codeのトークン消費を抑えるサブエージェント運用
Claude Codeでサブエージェントを使うとトークン消費が増えます。モデル選択・maxTurns・スポーンプロンプト最適化・Agent Teamsとの使い分けなど、コスト削減の実践的な設定と運用パターンを整理します。
サブエージェントは並列調査やコンテキスト分離に有効ですが、使い方次第でトークン消費が急増します。この記事ではClaude Codeのサブエージェント利用時のコスト構造を整理し、費用対効果を高める運用パターンを具体的に説明します。
サブエージェントがトークンを多く使う理由
Claude Codeのサブエージェントは、それぞれが独立したコンテキストウィンドウを持ちます。メイン会話の汚染を防げる一方、各サブエージェントが起動するたびにCLAUDE.md・MCPサーバーのツール定義・Skills・スポーンプロンプトが自動的にロードされます。つまりサブエージェントを3つ同時に起動すると、その固定コストが3倍かかります。
Anthropicの公式ドキュメントによると、Claude Codeのエンタープライズ展開での平均コストは1開発者・アクティブ日あたり約$13、月あたり$150〜250です。全体の90%のユーザーではアクティブ日あたり$30以下に収まっていますが、サブエージェントを多用するワークフローでは跳ね上がりやすいのが実情です。
モデル選択が最大のコスト変数
サブエージェントのコストを決める最大の要因はモデルです。frontmatterのmodelフィールドで指定します。
| モデル | 速度 | コスト | 向くサブエージェントの用途 |
|---|---|---|---|
haiku | 速い | 安い | ファイル探索・検索・キーワード調査・単純なフォーマット整理 |
sonnet | 標準 | 標準 | コードレビュー・テスト生成・デバッグ・調整作業（省略時のデフォルト） |
opus | 遅め | 高い | セキュリティ深掘り・アーキテクチャ相談・複雑な推論 |
inherit | 親と同じ | 親と同じ | 親と同じモデルを使いたい場合 |
調査専用エージェントにはmodel: haikuを指定するのが鉄則です。読み取りと検索だけをするなら推論精度はほどほどで十分であり、コストを大幅に削れます。
---
name: repo-scout
description: コードベースを横断調査する。変更は行わない。
tools: Read, Grep, Glob, Bash
model: haiku
---一方、コードレビューや修正を伴う作業にhaikuを使うと精度が落ちてやり直しが増えるため、sonnet以上が適しています。コスト削減のつもりが修正コストで逆ザヤになるケースに注意してください。
maxTurnsで上限を設ける
サブエージェントにmaxTurnsを設定すると、エージェントが実行できるターン数に上限を設けられます。調査が終わらず無限に探索し続ける状況を防ぐシンプルな安全弁です。
---
name: repo-scout
description: コードベースを横断調査する。10ターン以内で完了する。
tools: Read, Grep, Glob
model: haiku
maxTurns: 10
---maxTurnsはカスタムサブエージェントのfrontmatterで設定できます。具体的な上限値はタスクの複雑さに合わせて調整してください。目安として、単純な調査なら5〜10、複雑なデバッグなら20〜30が参考になります。
スポーンプロンプトを短く保つ
サブエージェントを起動するときの指示文（スポーンプロンプト）はエージェントの初期コンテキストに入ります。詳細に書けば書くほど、各エージェント起動時のトークンが増えます。
重要な注意点は、CLAUDE.md・MCPサーバーのツール定義・Skillsがすでに自動的にロードされるという点です。これらに書いてある内容をスポーンプロンプトで繰り返す必要はありません。
# 冗長な例（NG）
repo-scoutエージェントを使って、以下を調査してください。
あなたはファイルを読むだけで編集は行わないAgentです。
変更を一切しないよう注意してください。……（同じ内容が続く）
# 簡潔な例（OK）
repo-scoutエージェントで認証モジュールのファイル構成を調査して「変更禁止」のような制約はカスタムエージェントのシステムプロンプトかtoolsのallowlistで設定済みなら、スポーンプロンプトでの繰り返しは不要です。
Agent Teamsのコストは標準の約7倍
Agent Teamsはエージェント同士が直接通信できる高度な並列化手段ですが、コストは別格です。公式ドキュメントには「Plan Modeで動作するAgent Teamsは標準セッションの約7倍のトークンを消費する」と明記されています。各チームメンバーが独自のコンテキストウィンドウを持ち、それぞれがClaudeの独立したインスタンスとして動作するためです。
Agent Teamsを使うときは次の点を守るとコストを抑えられます。
- チームメンバーには
sonnetを使う（Opusは使わない） - チームは小規模に保つ（各メンバーがコンテキストを持つので線形にコストが増える）
- 仕事が終わったらチームを解散する（アイドル状態でもトークンを消費し続ける）
- スポーンプロンプトを絞り込む（起動時にMCPとSkillsが自動ロードされるため）
通常の並列調査はサブエージェントで十分です。エージェント同士のフィードバックが不可欠な競合仮説検証などの高度な場面だけAgent Teamsを使う使い分けが費用対効果を高めます。
サマリー指示でメインコンテキストを守る
サブエージェントは独立したコンテキストで動きますが、返ってくる結果はメイン会話に積み重なります。結果が詳細すぎると、今度はメイン会話のコンテキストが圧迫されます。
スポーンプロンプトにサマリー形式の指示を入れることで消費量を制御できます。
repo-scoutを使って認証モジュールを調査してください。
結果は次の形式で、400字以内でまとめてください：
- 調査したファイル数
- 主要な関数名（最大5件）
- 注目すべき点この「返答は○字以内」「箇条書き最大○点」という指示は、並列調査全般でのコンテキスト節約の基本です。詳しくは「複数のAIエージェントで調査を並列化する実践パターン」で解説しています。
/usageでリアルタイム監視
/usage セッション中のトークン消費量を確認するには/usageコマンドを使います。セッションの合計コスト・API呼び出し時間・コード変更行数が表示されます。APIユーザーには実際のコスト見積もりが、サブスクリプションユーザーにはプランの使用量が表示されます。
ステータスラインに常時表示させることもできます。設定後はプロンプトの横にコンテキスト使用率が表示され、早期に過剰消費を検出できます。
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYを設定すると、同時に実行するツール呼び出しの最大数を制限できます。サブエージェントが並列に大量のツールを呼ぶ状況でレート制限に引っかかる場合の調整弁として使えます。
思考トークンの調整
Claude Code v2以降では「拡張思考（extended thinking）」がデフォルトで有効です。複雑な推論精度が上がる一方、思考トークンは出力トークンとして課金され、1リクエストあたり数万トークンに達することがあります。
単純なタスクには思考トークンを減らす設定が有効です。
MAX_THINKING_TOKENS=8000 claude または/effortコマンドでセッション内のエフォートレベルを下げることもできます。サブエージェントが単純な調査を行う場合は、エージェント定義のシステムプロンプトに「簡潔に考えること」と明記する方法もあります。
サブエージェント運用コスト削減チェックリスト
- 調査専用エージェントには
model: haikuを設定しているか -
maxTurnsで上限を設けて無限探索を防いでいるか - スポーンプロンプトはCLAUDE.mdと重複しない簡潔な内容か
- Agent TeamsはAgent間通信が必要な場面だけに限定しているか
- 結果のサマリー形式をスポーンプロンプトで指定しているか
-
/usageでセッション消費を定期的に確認しているか - 単純なタスクでOpusを使っていないか
次に読むおすすめ記事：
- 「Claude Codeのサブエージェントはいつ使うべき？判断基準を整理」：コスト観点も含めたサブエージェント使用判断の5問フロー
- 「Claude Codeに必要な情報だけ渡すコンテキスト設計」：サブエージェント以外も含めたトークン消費全体の管理戦略
