Agent Teamsのコスト管理 — トークン消費を抑える設定

Agent Teamsはサブエージェントと何が違い、なぜ高くつくのか

Agent Teamsは、複数のClaude Codeインスタンスを同時に起動する仕組みです。リードのセッションがチームメイトを立ち上げ、各チームメイトは独立したコンテキストウィンドウで並行して作業します。1本の会話履歴を積み上げる通常セッションに対し、人数分の履歴が同時に積み上がるので、消費のペースが変わります。契約形態別の上限設定など基本のコスト管理はClaude Codeのコスト管理にあるので、ここではチーム特有の増分を扱います。

通常のチーム編成では、稼働中の人数で倍率が変わります。通常セッションの目安も、企業導入全体の平均値です。90%のユーザーは1稼働日あたり$30未満に収まっているので、チームの増分はこの幅と比べて見ると規模感がつかめます。まず小さなチームで自分の環境の増分を測るのが確実です。

有効化のしかたと、オフに戻す方法

Agent Teamsは実験機能で、既定では無効です。環境変数かsettings.jsonのenvでCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSを1にすると有効になります。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

変数が無い状態ではチームが作られず、Claudeがチームメイトを提案することもありません。値を0にすると、名前付きのサブエージェントが従来どおりサブエージェントとして起動します。コスト調査で「チームのせいか」を切り分けたいときは、この変数をオンオフして同じ作業を比べる方法があります。

有効化中は、Claudeが名前を付けたサブエージェントがチームメイトとして起動します。頼んでいないのにチームが組まれ、人数分の消費が乗ることがあります。-p付きの非対話モードでは、Agent SDKのセッションを含め、チームメイトは起動しません。

人数とタスクの切り方で、消費の大半が決まる

チームメイトの消費は人数にほぼ比例して増えます。公式の実装ガイドには「15個の独立したタスクがあっても、まず3人から始める」とあり、人数を増やすほど調整の手間が増え、並列化の効果も頭打ちになります。

タスクの粒度も効きます。小さすぎると調整のやり取りが利益を上回り、大きすぎると確認なしに長く走って、やり直しの無駄が増えます。関数・テストファイル・レビュー1件のように、成果物が明確で完結する単位が目安です。

起動プロンプトも最初から全員のコンテキストに乗ります。チームメイトはCLAUDE.md、MCPサーバー、スキルを自動で読み込むので、そこへ背景説明を長く足すと、1人あたりの初期コストが人数分に膨らみます。担当範囲と完了条件に絞った文面なら軽く済みます。

auth モジュールを3人で並行レビューする。各自 Sonnet を使うこと。
1人目: トークン処理、2人目: セッション管理、3人目: 入力検証。
担当外のファイルは読まない。指摘が出揃ったらリードへ報告して終了する。

初めて試すなら、コードを書かない調査やPRレビューのように境界のはっきりした作業が向いています。並列実装は同じファイルの上書きや調整が絡むので、増分が読みにくくなります。

全員がOpusになる経路を避ける — モデルの決まり方

公式は、チームメイトにSonnetを使うことを勧めています。注意したいのは、指定しなかったときの既定がリードのモデルになる点です。リードをOpusで動かしていると、何も言わなければチーム全員がOpusになります。

全員を1つのモデルに固定したいときは、CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1を併用します。1番目と2番目の指定が効かなくなり、v2.1.257以降で使えます。チームメイトのモデルは起動時に固定され、/modelで変わるのはリードのほうだけです。組織のavailableModelsが許可していないモデルを選ぶと、別のモデルに置き換わります。

チームメイトはリードのeffort(推論の深さ)も引き継ぎます。リードを高いeffortで動かしたまま調整役を増やすと、その設定が人数分に効いてきます。v2.1.287のclaude --helpにある--modelは「現在のセッション」のモデルを指すので、チームメイト別の指定は起動プロンプトか定義で行います。

止めたつもりで走り続けるケース

稼働中のチームメイトは、終了するかセッションが終わるまでトークンを消費し続けます。ここで見落としやすい点が3つあります。

• 行が消えても止まっていない: アイドルのチームメイトの行は、パネル全体がアイドルになって30秒後に非表示になります。非表示のチームメイトは停止ではなく、動作中で呼び出し可能なままです。アイドルが3人を超えると、あふれた分の行はN idle agentsの1行に畳まれ、Enterで展開できます
• 終了は依頼ベース: 名前を指定して終了を頼むと、リードが終了リクエストを送ります。チームメイトは承認することも、理由を添えて断ることもできます。現在のリクエストやツール呼び出しが終わってから止まるため、時間がかかる場合があります
• resumeでは戻らない: /resumeや/rewindはインプロセスのチームメイトを復元しません。再開後は新しく起動し直すことになり、起動コストも新たにかかります。リードが存在しないチームメイトへ連絡しようとすることがあるので、その場合は新しいチームメイトを起動させます

人手の終了確認に頼りたくないときは、チームメイトがアイドルになる直前に走るTeammateIdleフックがあります。終了コード2で終えるとフィードバックを返して作業を続けさせる仕組みで、完了条件を満たすまで止めない用途です。終了を早めたいときは、起動プロンプトに「指摘が出揃ったら報告して終了する」と完了条件を書いておくほうが手早く済みます。

チームメイトは作業を終えて止まると、最終的な回答を添えてリードへ自動で通知します。APIエラーでターンが終わったときも、エラー文を添えて失敗を知らせます。メッセージは受け手へ自動で届くので、リードが更新を確認しに回る必要はありません。

タスクの割り当ても、リードが指名する方法と、終えたチームメイトが未割り当てで依存の無い次のタスクを自分で取る方法があります。同じタスクを複数人が取る競合はファイルロックで防がれるので、タスクを細かく切っても二重作業は起きません。作成や完了の時点で割り込みたいときは、TaskCreatedとTaskCompletedフックが使えます。終了コード2で作成や完了を止め、理由をフィードバックとして返せます。

planモードにも注意が要ります。リードがplanモードのとき起動したチームメイトは、計画ができるまで読み取り専用で動き、計画の承認依頼をリードへ送ります。この承認はリード側のセッションで、リードが内容を確認せずに即座に行われます。編集とコマンドの実行は通常の権限確認を通りますが、計画の中身をリードがレビューする工程は無いと考えておく必要があります。

セッション全体の消費が膨らむほかの要因

チームだけが原因とは限りません。数時間開いたセッションでは、次のような要因が重なって使用量が膨らみます。

チームメイトの消費が疑わしいときは、これらも同時に点検すると切り分けが早くなります。

消費を数字で確認する

Pro・Max・Team・Enterpriseのプランでは、/usageにAttribution欄が出ます。スキル・サブエージェント・プラグイン・個別のMCPサーバーごとの使用割合を示す欄です。内訳はこのマシンのローカル履歴から計算した概算で、ほかの端末やclaude.aiの使用は含まれません。

切り分けには、/usageのほかの行も使えます。Loops行は、特に重い/loopなどのスケジュールタスクを1件ずつ並べるもので、v2.1.242以降で出ます。Prompt cache (main)行はキャッシュの状況を示しますが、対象はメイン会話だけでサブエージェントは含まれず、v2.1.251以降の表示です。チームメイト側のキャッシュ状況は、この行からは読み取れません。

チームメイト単位で追うなら、Claude CodeのOpenTelemetryで利用量とコストを可視化する方法があります。ユーザー単位・モデル単位の内訳を自前の基盤へ流し込めます。

チームメイトが長く待機すると、プロンプトキャッシュが切れて次のリクエストで全文脈が再処理されます。メイン会話のキャッシュは、サブスクリプションなら1時間、API keyやクラウドプロバイダーでは5分です。ただしインプロセスのチームメイトの要求は別枠で、サブスクでも既定は5分です。使用量クレジットを使い始めたときも、メイン会話が5分に縮みます。

チームメイトのキャッシュを1時間にするには、subagentPromptCacheTtlを1hにします。環境変数ならCLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTLで、どちらもv2.1.242以降で使えます。1時間のキャッシュ書き込みはAPIの課金単価が高くなるため、待機が長いチームで再処理が目立つときに効く設定です。仕組みはAnthropic APIのPrompt Cachingを理解するにまとめています。

Team・Enterpriseのシート利用枠は、5時間のローリングウィンドウと週次ウィンドウでリセットされます。API従量やクラウド経由の契約には枠がなく、消費した分がそのまま請求に反映されます。

並行が必要か、順番で足りるかを先に切り分ける

並列が効くのは、チームメイト同士が互いを待たずに進められる作業です。順番に進める作業、同じファイルを編集する作業、依存関係が多い作業は、単一のセッションかサブエージェントのほうが向いています。速度と引き換えにコストが人数分乗る設計なので、時間短縮の価値が追加コストを上回る作業かを、起動の前に見ておくことになります。

よくある質問

チームメイトに権限モードを個別に決められますか

起動時に個別の権限モードは決められず、リードと同じモードで始まります(dontAskは引き継がれません)。起動後に個々のチームメイトのモードを変えることはできます。

まとめ

チームの追加コストが見合うかは、並列にして縮む時間の価値で決まります。

詳しい契約形態別の上限設定はClaude Codeのコスト管理に、表示切り替えやtmux連携はteammateModeでAgent Teamsの表示方法を切り替えるにあります。