Claude Code Agent Teams 実践ガイド 2026｜Subagents との使い分け・実行ログ115タスクの実測・コスト統制

「Claude Code に 5 人のチームを組ませたら開発が 5 倍速くなるのか」——Agent Teams（エージェントチーム）という機能名を聞いたとき、多くの人が最初に思い浮かべるのはこの期待です。

結論から言うと、5 倍にはなりません。速くなる仕事はありますが、それは「並列に探索する価値がある仕事」に限られ、そうでない仕事に使うとトークン消費だけが増えます。公式ドキュメントも「エージェントチームは調整のオーバーヘッドを伴い、単一セッションよりも大幅に多くのトークンを使う」と明記しています。

本記事は、Agent Teams を使うか使わないかを判断できる状態にすることを目的にしています。機能紹介だけでなく、Subagents や Worktree 並列との使い分け、実際の実行ログを数えた結果、コストが実際いくらになるのか、そして受託開発の現場で使うときに誰がどこで承認するのか——ここまでを扱います。

この記事で分かること

• Agent Teams の 4 つの構成要素（チームリード・チームメイト・共有タスクリスト・メールボックス）と、Subagents との構造的な違い
• Subagents / Agent Teams / Worktree 並列 / デスクトップ並列の使い分けマトリクス（目的・粒度・コスト・巻き戻し・承認位置の 5 軸）
• 検索上位の解説記事がすでに現行仕様と食い違っている 4 点
• 実行ログ 12 セッション・115 タスクを数えて分かった、チームが実際に組まれる頻度と未完了タスクの割合
• 公式の「約 7 倍（plan mode 時）」を日本円の金額に落としたコスト試算と、1 回の実行単位では金額のハード上限が掛けられないという構造的な事実
• 受託開発で使うときの承認ポイント・レビュー責任・監査ログとして残るもの／残らないもの

結論 — Agent Teams は「並列に探索する価値がある仕事」にだけ使う

Agent Teams とは、複数の Claude Code インスタンスを 1 つのチームとして協調させる実験的機能です。1 つのセッションがチームリードとして働き、チームメイトはそれぞれ独立したコンテキストウィンドウを持ち、リードを経由せずに直接メッセージを交換します。

判断の結論を先に置きます。

「AI が勝手にチームを組んで全部やってくれる」機能ではありません。人間が仕事を切り分けられている範囲でだけ効く、と考えるのが実態に近いです。

Agent Teams とは — 4 つの構成要素

Agent Teams は、次の 4 つの要素で構成されます。公式ドキュメントのアーキテクチャ節に定義されているものです。

これらはすべてローカルのファイルとして実体を持ちます。

• チーム設定: ~/.claude/teams/{team-name}/config.json
• タスクリスト: ~/.claude/tasks/{team-name}/
• メールボックス: ~/.claude/teams/{team-name}/inboxes/{agent-name}.json

{team-name} はセッション由来の名前で、session- に続けてセッション ID の先頭 8 文字が付きます。どちらもセッション開始時に自動生成され、チームメイトが参加・待機・離脱するたびに更新されます。チーム設定ディレクトリはセッション終了時に削除されますが、タスクリストのディレクトリはローカルに残ります（アップロードはされません）。保持期間はセッション履歴と同じ cleanupPeriodDays（既定 30 日）に従います。

Subagents との違いは「通信」と「調整」

同じ「並列化」でも、Subagents と Agent Teams は動き方が違います。公式ドキュメントの比較表を整理すると次のようになります。

要するに、結果だけ欲しいなら Subagents、途中で議論させたいなら Agent Teams です。「セキュリティ観点のレビュー結果を 1 つ返してほしい」なら Subagents で足ります。「セキュリティ担当とパフォーマンス担当に互いの指摘をぶつけさせたい」なら Agent Teams の出番です。

タスクの状態と依存関係

共有タスクリストのタスクは、pending（未着手）・in progress（進行中）・completed（完了）の 3 状態を取ります。タスク同士に依存関係を設定でき、依存先が完了していない pending タスクは取得できません。ある依存タスクが完了すると、依存していたタスクのブロックは自動的に解除されます。

タスクの取得にはファイルロックが使われており、複数のチームメイトが同時に同じタスクを取得しようとしたときの競合を防いでいます。

Subagents / Agent Teams / Worktree 並列 / デスクトップ並列の使い分けマトリクス

Claude Code で「並列にやる」方法は 1 つではありません。多くの解説記事は Agent Teams 単体、あるいは Subagents との 2 択で語りますが、実際には 4 つの選択肢があり、どれを選ぶかは「失敗したときにどう巻き戻すか」で決まります。

この表で最も重要なのは巻き戻しの行です。Agent Teams の in-process チームメイトは /resume と /rewind で復元されません。公式ドキュメントは制限事項として「セッションを再開した後、リードが存在しないチームメイトにメッセージを送ろうとすることがある」と明記しています。

つまり、やり直しが前提の作業に Agent Teams を使うと、やり直しのコストが高くつきます。実装の試行錯誤なら Worktree 並列のほうが安全です。ブランチごと捨てれば済むからです。

判断の順序としては次のようになります。

1. 本体のコンテキストを汚さずに調べたいだけ → Subagents
2. 同じ問題を複数の視点でぶつけたい → Agent Teams
3. 独立したブランチの作業を同時に進めたい → Worktree 並列
4. 上記を GUI で楽にやりたい → デスクトップ並列（⌘+N）

なお公式ドキュメントは、チームを組む前に軽い選択肢で足りないかを確認するよう促しています。Subagents は単一セッション内で動き、クロスセッションメッセージングを使えば、自分で立ち上げた複数セッション間で Claude が知見を受け渡すこともできます。

有効化と表示モード（2026 年 9 月時点の現行仕様）

Agent Teams は既定で無効です。有効化する方法は 2 通りあります。

設定ファイルで有効化する

~/.claude/settings.json に環境変数を書きます。

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

シェルの環境変数で有効化する

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

この変数がない状態では、セッション開始時にチームは構成されず、チームのディレクトリも書き込まれず、Claude はチームメイトを起動も提案もしません。

有効化すると通常の委譲の挙動も変わる

ここは見落とされがちですが重要です。Agent Teams を有効にすると、通常の Subagent の起動挙動まで変わります。

Claude は自分で Subagent に名前を付けることがあります。そして Agent Teams が有効な間、名前を付けられた Subagent はチームメイトとして起動します。つまり、あなたがチームを頼んでいなくてもチームが形成されうるということです。

元に戻したい場合は、環境変数を 0 に設定します。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

新しいセッションを開始する必要はありません。設定ファイルの env の値は保存時に実行中のセッションへ再適用され、Subagent を起動するたびに変数が読み直されます。

ただし優先順位に注意が必要です。ユーザー設定で 0 にするとシェルの export を上書きしますが、プロジェクト設定・ローカル設定・--settings は後から適用されるため、そこで 1 になっていればそちらが勝ちます。組織の管理設定（managed settings）はさらにすべての後に適用されます。

表示モードは既定で in-process

チームメイトの表示方法は 2 つあります。

• in-process: すべてのチームメイトがメインのターミナル内で動く。追加のセットアップは不要で、どのターミナルでも動く
• 分割ペイン（split panes）: チームメイトごとにペインが割り当てられる。全員の出力を同時に見られる。tmux または iTerm2 が必要

既定値は "in-process" です。~/.claude/settings.json で変更できます。

{
  "teammateMode": "auto"
}

セッション単位で指定する場合はフラグを使います。

claude --teammate-mode auto

--teammate-mode は実験的なフラグで、claude --help には表示されません。

設定値は "in-process" / "auto" / "tmux" / "iterm2" の 4 つです（"iterm2" は v2.1.186 以降で指定できます）。"auto" は、すでに tmux セッション内で動いている場合、または iTerm2 で it2 CLI がインストールされている場合に分割ペインを有効にし、それ以外では in-process にフォールバックします。

分割ペインは VS Code の統合ターミナル・Windows Terminal・Ghostty ではサポートされません。Windows で使いたい場合、既定の in-process モードはどのターミナルでも動くのでそちらを使ってください。

チームメイトの操作

in-process モードでは、プロンプト入力欄の下に表示されるエージェントパネルでチームメイトを操作します。

チームメイトが待機状態になると、パネル内の行は 30 秒後に非表示になります（v2.1.199 以降の挙動で、パネル内の全エージェントが待機状態になってから 30 秒）。行が消えてもチームメイトは動いており、名前を指定すればメッセージを送れます。待機中のチームメイトが 3 人を超えると、4 人目以降は 2 idle agents のような 1 行にまとまります。この行を選択して Enter を押すと展開でき、Esc で再びたたみます。作業中のチームメイト・失敗したチームメイト・表示中のチームメイトは、常に独立した行を保ちます。

検索上位の情報はすでに古い — 現行仕様との差分 4 点

Agent Teams が話題になったのは 2026 年初頭で、検索ボリュームは 2026 年 2 月をピークにその時期へ集中しています。日本語の解説記事にも、この時期に書かれたものが残っています。しかし機能は継続的に変更されており、検索上位に並ぶ記事の手順の一部は、現在そのまま実行しても意図した結果になりません。2026 年 9 月時点の公式ドキュメントと突き合わせた差分を挙げます。

特に 2 番目は実害があります。リードが自分で実装を始めてしまうのを止めたくて Shift+Tab を押すと、現在は権限モードが acceptEdits や plan に切り替わるだけです。それどころか循環は plan の次に任意モードへ進み、両方が有効なら bypassPermissions を経由して auto に至るため、押し続けると意図と逆に権限が緩みます。

現行仕様でリードの先走りを止めたい場合の正攻法は 2 つです。

1. plan mode を使う: リードを plan mode に切り替えてからチームメイトを頼むと、そのチームメイトは計画ができるまで読み取り専用の plan mode で動きます。ただし公式が「約 7 倍」としているのはまさにチームメイトが plan mode で動く場合なので、安全性とコストのトレードオフになります
2. 明示的に待たせる: 公式ドキュメントのベストプラクティスにそのままの指示文があります

Wait for your teammates to complete their tasks before proceeding

この「リードが自分で実装を始めてしまう」現象は、後述する実行ログの実測でも確認できました。

実行ログ 12 セッション・115 タスクを数えた

ここからは公開情報ではなく、koromo の開発機に残っていた実際の実行ログを集計した結果です。

前提を明示します。 これは本記事のために新しくベンチマークを実行したものではありません。通常業務で CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を有効にしたまま Claude Code を使い続けた結果として ~/.claude/tasks/ と ~/.claude/teams/ に蓄積されていたログを、後から数えたものです。対象期間は 2026 年 8 月 8 日〜8 月 19 日、環境は macOS / Claude Code v2.1.145 です。バージョンが現行より古い点はご留意ください。

集計結果

この数字から読み取れることが 3 つあります。

1. フラグを立ててもチームは滅多に組まれない。 12 セッション中 11 セッションでは、タスクに担当者が割り当てられた形跡がなく、チームメイトが動いた痕跡は残っていませんでした。共有タスクリストは、単一セッションの ToDo リストとして使われていただけです。公式ドキュメントも「Claude はタスクに基づいてチームメイトを起動するかどうかを判断する」「Claude がチームではなく Subagents を使うこともある」と書いていますが、その判断が実際にどれくらいの頻度でチーム編成に倒れるのかは、この数字が示すとおりです。Agent Teams を使いたいなら、明示的にチームを要求する必要があります。

2. タスクの状態は実際に取り残される。 公式が制限事項として挙げる「タスクの状態が遅れることがある」（チームメイトがタスクを完了としてマークし損ねる）は、14.8% という実測値として現れました。依存関係を設定したタスクがブロックされたまま止まる原因になるため、依存関係を多用する設計は避けたほうが無難です。

3. 依存関係はほとんど使われない。 115 タスク中 6 件だけで、しかも 1 セッションに集中していました。これは「Agent Teams はワークフローエンジンではない」という現実的な理解につながります。複雑な依存グラフを組ませるより、互いに独立したタスクに割り切って渡すほうが噛み合います。

唯一チームが組まれたセッションの中身

12 セッション中で実際にチームが編成された 1 件（2026 年 8 月 16 日）を、ファイルのタイムスタンプとメールボックスの記録から復元しました。

注目すべきは最後の 3 行です。6 タスク中 4 タスクはチームメイトに渡っていません。リードが半分を自分でやっています。前節で触れた「リードが自分で実装を始めてしまう」現象が、そのまま数字に出ています。

チームメイトを 2 体起動しておきながら、実際に並列化できたのは 6 タスク中 2 タスク。この構成なら、Subagents でも同等の結果が得られた可能性が高いというのが率直な評価です。

タスクとメールボックスの実ファイル構造

公開されている解説記事ではあまり触れられていない部分なので、実ファイルの構造を記載します。中身はプロジェクト固有の情報を含むため、フィールド名と形だけを示します（運用判断には不要な内容なので、仕様の裏取りが必要な方以外は次節へ進んで構いません）。

タスクは ~/.claude/tasks/{team-name}/{id}.json に 1 タスク 1 ファイルで置かれます。

{
  "id": "1",
  "subject": "タスクの件名",
  "description": "タスクの詳細な指示",
  "activeForm": "実行中に表示される進行形の文言",
  "owner": "teammate-name",
  "status": "completed",
  "blocks": [],
  "blockedBy": []
}

同じディレクトリに 0 バイトの .lock ファイルがあります。これが公式ドキュメントの言うファイルロックの実体で、複数のチームメイトが同時に同じタスクを取得しようとしたときの競合を防いでいます。

メールボックスは ~/.claude/teams/{team-name}/inboxes/{agent-name}.json に JSON 配列として置かれます。要素は次の形です。

{
  "from": "team-lead",
  "text": "メッセージ本文、または構造化メッセージのJSON文字列",
  "timestamp": "2026-08-16T01:01:02.283Z",
  "msgV": 1,
  "msg_id": "00000000-0000-0000-0000-000000000000",
  "type": "message",
  "read": false
}

タスク割り当てのような構造化メッセージは、text フィールドの中に JSON 文字列として入れ子で格納されていました。

{
  "type": "task_assignment",
  "taskId": "3",
  "subject": "タスクの件名",
  "description": "タスクの詳細",
  "assignedBy": "team-lead",
  "timestamp": "2026-08-16T01:01:02.283Z"
}

リード自身のメールボックスは main.json という名前で、送信者名は team-lead として記録されています。

なお公式ドキュメントは、Claude Code がメールボックスファイルを読むたびに全エントリを検証し、形式に合わないエントリはエラーとして報告したうえでファイルから削除する、と説明しています（v2.1.207 より前は、不正なエントリ 1 件で毎秒エラーが繰り返され、手動でファイルを削除するまでそのメールボックスの配信がブロックされていました）。また、メッセージが「送信済み」と報告されるのは受信側のメールボックスファイルへの書き込みが成功したときだけで、ディスク容量不足などで書き込みに失敗した場合は送信側にエラーが返り、何も送信されません。

コスト設計 — 公式の「約 7 倍」を金額に落とす

Agent Teams のトークン消費について、公式ドキュメントには明確な数字があります。

エージェントチームは、チームメイトが plan mode で動作するとき、標準的なセッションの約 7 倍のトークンを使用する

条件が付いている点に注意してください。「チームメイトが plan mode で動作するとき」です。この条件を外して「Agent Teams は 7 倍」と引用すると不正確になります。

公式が示すコストの実額アンカー

同じ公式ドキュメントには、Claude Code 全体のコスト実績も書かれています。

ここに「約 7 倍」を単純に当てると、1 日を丸ごと plan mode のチーム実行に置き換えた極端なケースで $91（約 14,105 円）となり、90 パーセンタイルの $30 の 3 倍を超えます。実際には 1 日のすべてがチーム実行になることはないので、これは上限側のシナリオとして読んでください。

チーム人数とモデル別の試算

より実務的に、1 回のチーム実行あたりのコストを試算します。これは実測値ではなく、公開されている API 料金からの計算です。前提を明示します。

• 1 インスタンスが抱えるコンテキスト: 10 万トークン
• 1 回の実行で 1 インスタンスが行うリクエスト数: 30 回
• 1 リクエストあたりの平均出力: 3,000 トークン
• プロンプトキャッシュが効いている（初回に 5 分キャッシュへ書き込み、以降は読み出し）
• 料金は 2026 年 9 月 6 日時点の Anthropic 公式 API 料金、1 ドル 155 円換算
• 円は丸める前のドル額から換算しているため、表に載せたドル額との積とは 1 円程度ずれることがあります

料金の根拠は次のとおりです（すべて 100 万トークンあたり）。

軽い調査だけを担当させるチームメイトなら、Haiku 4.5 も選択肢になります。

上のコスト試算表はインスタンス数にほぼ比例するので、リード＋チームメイト 3 人なら単一セッションの 4.0 倍、5 人なら 6.0 倍です。公式の「約 7 倍」はチームメイトが plan mode で動く場合の値なので、計画を立てるための追加の読み込みが上乗せされる分、この単純比例よりやや大きくなる、という関係になります。

公式ドキュメントが「チームメイトには Sonnet を使う」と推奨している理由も、この表を見ると分かります。同じ構成で Opus は Sonnet の 約 2.5 倍（言い換えると Sonnet は Opus の約 40%）です。

見落とされがちな罠 — チームメイトのキャッシュは既定 5 分で切れる

ここが本記事で最も注意を促したい点です。

公式ドキュメントには次の記述があります。

in-process のチームメイトのリクエストは、メインの会話のキャッシュ TTL バケットの外側に置かれるため、そのキャッシュは Claude のサブスクリプションを利用している場合でも既定で 5 分間保持される

つまり、チームメイトが 5 分以上待機すると、次のターンでキャッシュが切れており、コンテキスト全体を割引なしの通常単価で再処理します。上の前提で計算すると、キャッシュが毎回失効した場合のコストは次のようになります。

キャッシュが全失効すると、構成にかかわらずコストは 約 4 倍に膨らみます（前節のインスタンス数による 4.0 倍とは別軸の増加です）。

チームメイトが互いの完了を待つ構成、つまり依存関係のある設計ほど待機時間が長くなり、この罠を踏みやすくなります。

対策は subagentPromptCacheTtl を 1h に設定することです。ただし 1 時間キャッシュへの書き込みは課金レートが上がります（Sonnet 5 で 100 万トークンあたり $2.50 → $4.00）。上の前提での追加コストは 1 インスタンスあたり約 $0.15 で、最大 $5.17 の無駄を防げる計算になるため、待機の長いチーム構成では設定する価値があります。

プラン別の料金構造そのものについてはClaude Code の料金プラン比較で詳しく扱っています。

1 回の実行に金額の上限は掛けられない — 3 層で統制する

「暴走したら怖いので、金額の上限を設定して使いたい」——法人で導入を検討する際、必ず出る要望です。

結論から言うと、1 回の実行や 1 セッションを対象にした金額のハード上限は掛けられません。これは設定不足ではなく、現在の仕様上の構造です。組織やワークスペース単位の支出上限は存在しますが、粒度が粗く、個々の実行の暴走をその場で止めることはできません。

なぜ掛けられないのか

Claude Code には --max-budget-usd という、API 呼び出しの支出上限を設定するフラグがあります。上限に達すると Subagent の起動が Budget limit reached で失敗し、実行中のバックグラウンド Subagent も停止されます（この上限強制の挙動は v2.1.217 以降）。

しかし公式 CLI リファレンスは、このフラグに条件を付けています。

API 呼び出しに費やす最大金額（print mode のみ）

一方、Agent Teams の公式ドキュメントには次の記述があります。

チームメイトの起動には対話型セッションが必要です。-p フラグを使う非対話モード（Agent SDK のセッションを含む）では、Claude はチームメイトを起動しません

この 2 つは論理的に両立しません。--max-budget-usd が効くのは print mode だけで、print mode ではチームメイトが起動しない。したがって、Agent Teams が動いている状態にこのフラグを適用する方法は存在しません。

検索上位の解説記事は「トークンコストが高いので注意」で止まっており、この非対称性に触れているものは見つけられませんでした。しかし法人導入の稟議では、まさにここが問われます。

3 層でコストを統制する

ハード上限が使えない以上、統制は次の 3 層で組み立てることになります。

第 1 層の具体策は、公式ドキュメントの「エージェントチームのトークンコスト」節にそのまま列挙されています。

• チームメイトには Sonnet を使う。調整タスクにおいて能力とコストのバランスが取れている
• チームを小さく保つ。チームメイトごとに独自のコンテキストウィンドウが動くため、トークン使用量はチームサイズにおおむね比例する
• spawn プロンプトを絞る。チームメイトは CLAUDE.md・MCP サーバー・スキルを自動的に読み込むが、spawn プロンプトに書いたものはすべて最初からコンテキストに乗る
• 作業が終わったチームメイトは停止する。アクティブなチームメイトは、終了するかセッションが終わるまでトークンを消費し続ける

ただし、モデル指定は無条件に効くわけではありません。Claude Code がチームメイトのモデルを決める優先順位は、①spawn プロンプトで名前を挙げたモデル ②Subagent 定義から起動した場合はその定義の model ③CLAUDE_CODE_SUBAGENT_MODEL ④リードの現在のモデル、の順です。v2.1.251 より前は CLAUDE_CODE_SUBAGENT_MODEL がこの順序の先頭でした。

さらに、組織が availableModels の許可リストを設定している場合、Claude Code は選んだモデルを許可リストと照合し、ブロックされた値は別のモデルに差し替えます。つまり企業導入では「Sonnet を指定したつもりが別のモデルで動いていた」が起こりえます。実際に使われたモデルは /usage で確認してください。

4 つ目の「作業が終わったチームメイトは停止する」は特に効きます。公式は「長いセッションで使用量が増える理由」の一つとして「各アクティブなチームメイトは終了するまでトークンを消費し続ける」を挙げています。停止は名前を指定して依頼します。

Ask the researcher teammate to shut down

リードがシャットダウン要求を送り、チームメイトは受け入れて正常終了するか、理由を添えて拒否します。

チーム人数の目安

公式ドキュメントの推奨は明確です。

• 多くのワークフローでは 3〜5 人から始める
• 独立したタスクが 15 個あるなら、3 人が良い出発点
• 1 人あたり 5〜6 タスクが、全員を稼働させつつリードが再割り当てできる状態を保つ
• 「散漫な 5 人より、焦点の定まった 3 人のほうが良い結果を出すことが多い」

トークンコストは人数に線形にスケールし、調整のオーバーヘッドも増え、ある点を超えると人数を増やしても比例して速くはなりません。

向く仕事・向かない仕事の判断表

公式ドキュメントが挙げる「最も効果的なユースケース」と「単一セッションのほうが効果的なケース」を、受託開発の実タスク名に翻訳した判断表です。

向く仕事

向かない仕事

タスクの大きさについて、公式は次の基準を示しています。小さすぎると調整のオーバーヘッドが利得を超え、大きすぎるとチームメイトが確認なしに長時間動いて無駄な作業のリスクが増えます。ちょうど良いのは「1 つの関数、1 つのテストファイル、1 つのレビュー」のように、明確な成果物を生む自己完結した単位です。

初めて使うなら、コードを書かない読み取り専用のタスクから始めるのが公式の推奨です。PR のレビュー、ライブラリの調査、バグの調査。これらは並列実装に伴う調整の難しさなしに、並列探索の価値を体感できます。

受託開発で使うときの承認・レビュー責任・監査ログ

ここからは、受託開発や法人での導入を前提にした設計の話です。個人利用では気にならない論点が、他社のコードベースを預かる立場では効いてきます。

承認はリードセッションに集約される

チームメイトの権限まわりの仕様は次のとおりです。

• チームメイトはリードの権限設定を引き継いで起動する。リードが --dangerously-skip-permissions で動いていれば、すべてのチームメイトもそうなる
• 起動後に個別のチームメイトのモードを変更できるが、起動時に個別指定はできない
• チームメイトの権限プロンプトはリードのセッションに表示されるので、そこで承認する

運用上の含意は明確です。リードセッションの前に座っている人が、チーム全員分の承認責任を負います。5 人のチームを組んで席を外すと、承認待ちで全員が止まるか、あるいは権限を緩めてあった場合はレビューされずに進みます。

公式ドキュメントも「権限プロンプトが多すぎる」場合の対処として、事前に権限設定で一般的な操作を承認しておくことを勧めていますが、これは裏を返せばチームを組むほど事前承認の範囲を広げたくなる圧力がかかるということです。受託開発では、この圧力に対して「どこまで事前承認してよいか」を先に決めておく必要があります。

plan 承認だけは例外 — リードが自動承認する

ここは監査上、特に注意すべき仕様です。

チームメイトが計画を終えると、リードに plan 承認リクエストを送ります。このとき公式ドキュメントは次のように書いています。

Claude Code はリクエストが到着し次第、リードがレビューすることなくリードのセッションで計画を承認する

つまり、チームメイトの計画は人間のレビューを経ずに承認されます。計画に基づく編集やコマンドの実行は通常の権限プロンプトを通りますが、「計画そのものが妥当か」の判断は自動で通過します。

受託開発でこれを使う場合、「計画は人が見た」と説明できない点を認識しておく必要があります。人のレビューを挟みたいなら、チームメイトに計画させるのではなく、リード側で計画を作って人が確認し、確定した作業をタスクとして割り振る運用にしてください。

エージェント間のメッセージでは承認の又貸しができない

セキュリティ上、重要な設計になっている部分です。

あるエージェントが SendMessage で別のエージェントにメッセージを送ると、Claude Code は受信側に対して「このメッセージは人間ではなく別の Claude セッションから来た」と伝えます。その結果、次のことが保証されます。

• チームメイトは、あなたに代わって権限プロンプトを承認したり同意を与えたりできない
• ある操作を拒否されたチームメイトが、別のチームメイトに頼んでチェックを迂回することはできない

さらに auto モードでは、分類器がエージェント間のメッセージに 2 つのチェックを適用します。別のエージェントから中継された承認の主張を、あなたからの確認ではなく信頼できない入力として扱うこと。そして各メッセージを配信前にレビューし、ブロックしたメッセージは受信者に届かないことです。

これは「チームメイトが増えても承認の穴は増えない」という設計であり、法人導入の説明材料になります。一方で、承認のボトルネックは人間 1 人に残るという先ほどの話と表裏です。

監査ログとして何が残り、何が残らないか

「AI が何をやったか後から追える状態か」は、AI エージェント開発のガバナンスを考えるうえで避けて通れません。Agent Teams について、実ログを確認した結果は次のとおりです。

ただし実測では例外がありました。v2.1.145 の環境で、2026 年 8 月 16 日のチームディレクトリを確認したところ、config.json は削除済みでしたが inboxes/*.json は残っていました。クリーンアップが完全ではないケースがあるということです。

監査の観点で言えば、この状態は次を意味します。

• タスク単位の作業記録は残るが、レビュー証跡としては不十分。タスクの subject と description、担当者、最終状態は分かりますが、「なぜその判断をしたか」は残りません
• エージェント間の議論は原則として残らない。Agent Teams の価値の中心である「互いに反証させる議論」の中身が、後から検証できません
• クリーンアップの挙動はバージョン依存。残っていること前提の設計も、消えていること前提の設計も、どちらも危険です

したがって受託開発では、Agent Teams の出力そのものを成果物にせず、人がレビューして確定させた内容を PR やドキュメントに落とす運用が現実的です。git の履歴と PR のレビューコメントが監査証跡であり、~/.claude/tasks/ はそうではない、という整理になります。

hooks で品質ゲートを掛ける

自動化された歯止めを掛けたい場合、hooks を使う手があります。Agent Teams 向けに 3 つのフックが用意されています。

たとえば TaskCompleted でテストの実行を必須にすれば、「テストが通っていないタスクは完了にできない」という機械的なゲートになります。承認の責任が人間 1 人に集中する構造への、実用的な緩和策です。

失敗パターン 7 選と対策

公式ドキュメントのトラブルシューティングと制限事項、および実測から見えた失敗パターンをまとめます。

このほか公式が挙げる制限事項として、次があります。

• 1 セッション 1 チーム。追加の名前付きチームを作ることも、チームをセッション間で共有することもできない
• 入れ子のチームは作れない。チームメイトは自分のチームメイトを起動できない。チームを管理できるのはリードだけ
• リードは固定。メインセッションが生涯リードであり、チームメイトをリードに昇格させることも、リーダーシップを移譲することもできない
• シャットダウンに時間がかかる。チームメイトは現在のリクエストやツール呼び出しを終えてから終了する
• in-process のチームメイトはバックグラウンド Subagent を起動できない。チームメイトのバックグラウンド作業はリードのプロセスより長く生存できないため

分割ペインモードで tmux セッションが残ってしまった場合は、手動で終了させます。

tmux ls
tmux kill-session -t <session-name>

最初のチームを安全に動かす 7 ステップ

ここまでの内容を、最初の 1 回で踏む順番に並べ直します。読み取り専用のタスクから始め、コストに効く設定を先に入れておくのが安全です。

1. 読み取り専用のタスクを選ぶ — PR レビューや調査系から。判断基準は「向く仕事・向かない仕事の判断表」のとおりです
2. 環境変数で有効化する — ~/.claude/settings.json の env に CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を "1" で追加します。有効化すると、名前を付けられた Subagent もチームメイトとして起動するようになる点に注意してください
3. チームメイトのモデルに Sonnet を指定する — spawn プロンプトで「チームメイトには Sonnet を使って」と明示します。同じ構成なら Opus の約 5 分の 2（約 40%）のコストに収まります
4. 3 人から始める — 独立したタスクが 15 個あっても 3 人が出発点です（根拠は「チーム人数の目安」）
5. 役割とファイル所有権を明示する — 「1 人はセキュリティ、1 人はパフォーマンス、1 人はテストカバレッジ」のように重ならないレンズを割り当てます。実装を含む場合は担当ディレクトリも明示して上書きを防ぎます
6. 待機の長い構成なら subagentPromptCacheTtl を 1h にする — 既定の 5 分でキャッシュが切れると約 4 倍に膨らむためです
7. 終わったチームメイトを停止する — 「researcher チームメイトにシャットダウンを依頼して」のように名前を指定します

チームを起動するときの指示は自然言語で構いません。公式ドキュメントの例は次のようなものです。

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

日本語でも同様に指示できます。役割が互いに独立していて、待ち合わせなしに探索できることが、うまくいく構成の条件です。

よくある質問

まとめ — 「並列にできる仕事か」を先に判断する

本記事で確認した要点を整理します。

• 効くのは並列探索に価値がある仕事だけ。多観点レビュー、競合仮説のデバッグ、独立した新規モジュールの実装。逐次作業・同一ファイル編集・依存の多い作業では、単一セッションか Subagents のほうが速く安い
• フラグを立てても自動でチームにはならない。実測では 12 セッション中 11 セッションでチームメイトが起動していなかった。明示的に要求する必要がある
• コストはチーム人数に線形。公式値で plan mode 時に約 7 倍。in-process のチームメイトのキャッシュは既定 5 分で切れ、待機が長い構成ではさらに約 4 倍になりうる
• 1 回の実行単位では金額のハード上限を掛けられない。--max-budget-usd は print mode 専用で、print mode ではチームメイトが起動しない。組織・ワークスペース単位の支出上限はあるが粒度が粗く、統制は設計・組織の枠・可観測性の 3 層で組む
• やり直しに弱い。in-process のチームメイトは /resume /rewind で復元されない。試行錯誤が前提なら Worktree 並列を選ぶ
• 監査証跡としては不十分。タスクリストは残るがエージェント間の議論は残らず、チームメイトの計画はリードが自動承認する。成果物は人がレビューして PR に落とす運用にする

そして最も実務的な注意点は、検索上位に残っている解説記事には 2026 年 2〜3 月に書かれたものが含まれ、現行仕様と食い違っていることです。Delegate Mode は公式の権限モードに存在せず、TeamCreate / TeamDelete は v2.1.178 で廃止され、表示モードの既定は v2.1.179 で in-process に変わりました。設定手順で詰まったときは、公式ドキュメントを確認するのが最短です。

Agent Teams は「人間が仕事を切り分けられている範囲でだけ効く」機能です。逆に言えば、切り分けの設計こそが価値を決めます。並列にできる仕事なのかを先に判断し、できる仕事にだけチームを組む——これが現時点での実務的な結論です。