Claude Code Agent Teams実践ガイド — 設計パターン・コスト実測・使い分け判断フローまで

サブエージェントで物足りなくなったら次のステージへ。Claude Code Agent Teamsは、複数の独立したセッションがピアツーピアで通信し合う「チーム開発」をAIだけで実現する。本記事では、セットアップから設計パターン、トークンコストの実測感覚、そしてサブエージェントや/batchとの明確な使い分け基準まで、公式ドキュメントだけでは得られない実運用ノウハウを凝縮した。

Agent Teamsとは何か — サブエージェントとの本質的な違い

アーキテクチャの全体像：Team lead・Teammates・Task list・Mailbox

Agent Teamsは4つのコンポーネントで構成される。

チーム設定は ~/.claude/teams/{team-name}/config.json に保存され、各teammateのエージェントIDや名前が記録される。タスクリストは ~/.claude/tasks/{team-name}/ 配下で管理される。

サブエージェントは「部下」、Agent Teamsは「同僚」

サブエージェント（AGENT.mdで定義する軽量ワーカー）は単一セッション内で動作し、結果をメインエージェントに返すだけの一方向の関係だ。対してAgent Teamsでは、各teammateが独立したコンテキストウィンドウを持ち、teammate同士が直接メッセージをやり取りできる。

正直、最初は「サブエージェントを複数立てるのと何が違うの？」と思っていたが、使ってみると「チームメンバーが互いの作業状況を見ながら調整し合う」感覚がまったく別物だと分かる。

メッセージは自動配信されるため、ポーリングは不要。broadcastは全teammateにメッセージが届くためトークンコストが高くなる。基本はmessageで特定のteammateに送るのが鉄則だ。

セットアップと表示モード

環境変数の有効化と動作確認

Agent Teamsは実験的機能であり、デフォルトでは無効化されている。有効にするには環境変数を設定する。

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

または settings.json に記述する方法もある。

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

有効化後、Claude Codeに「このタスクをチームで進めて」と指示すれば、Claudeがチーム構成を提案してくれる。ユーザーの承認なしにチームが作成されることはない。

3つの表示モード（auto / tmux / in-process）の選び方

--teammate-mode フラグまたは settings.json の teammateMode で表示モードを切り替えられる。

# 単発でモードを指定
claude --teammate-mode tmux

# settings.jsonで恒久設定
# { "teammateMode": "in-process" }

tmuxモードにはtmuxまたはiTerm2（it2 CLI + Python API有効化）が必要。VS Codeの統合ターミナルやWindows Terminalでは分割ペインモードは動作しない点に注意。

チーム構成の設計パターン3選

パターン1：リサーチ並列 — 情報収集を分担して統合

複数のteammateがそれぞれ異なるソースを調査し、Team leadが結果を統合するパターン。市場調査や技術選定で有効。

3人のリサーチチームを作ってほしい。

タスク:
1. researcher-a: React Server Componentsの最新のベストプラクティスを調査
2. researcher-b: 競合サービス（Vercel, Netlify, Cloudflare）の料金体系を比較調査
3. researcher-c: 認証ライブラリ（NextAuth, Clerk, Lucia）の機能比較

各自の調査結果をTeam leadにmessageで報告して。
最後にTeam leadが統合レポートをまとめて。

パターン2：仮説競争 — 複数アプローチを同時試行

同じバグに対し、異なるアプローチで並列デバッグする。先に解決した方を採用する。

デバッグチームを2人作って。

問題: /api/usersエンドポイントが500エラーを返す

- debugger-a: データベース接続周りを調査（コネクションプール、タイムアウト設定）
- debugger-b: ミドルウェアとバリデーション周りを調査（認証、入力検証）

先に原因を特定した方がTeam leadにmessageで報告して。
もう一方にはbroadcastで調査停止を指示して。

タスクの依存関係を設定しておけば、あるタスクが完了するまで後続タスクがブロックされる仕組みも使える。

パターン3：クロスレイヤー協調 — フロント・バック・テストの同時進行

最もAgent Teamsの真価が発揮されるパターン。フロントエンド担当・バックエンド担当・テスト担当の3 teammatesが、messageで型定義やAPI仕様を共有しながら同時実装する。

ユーザープロフィール機能をチームで実装して。

チーム構成:
- backend: src/api/ 配下を担当。REST APIエンドポイントを実装
- frontend: src/components/ と src/app/ 配下を担当。UIを実装
- tester: src/__tests__/ 配下を担当。テストを作成・実行

ルール:
- backendがAPI仕様（エンドポイント、リクエスト/レスポンス型）を決めたら、
  frontendとtesterにmessageで共有すること
- 各自は自分の担当ディレクトリのファイルのみ編集すること
- 型定義ファイル src/types/user.ts は backendが作成し、
  他のメンバーは読み取り専用とすること

ここで重要なのが担当ファイルの明示的な分離だ。これを怠ると、同一ファイルへの同時書き込みで競合が起きる。タスク設計の段階でディレクトリレベルで責任範囲を分けるのが最善策になる。

使い分け判断フロー — サブエージェント / Agent SDK / /batch / Agent Teams

4つの選択肢の特性比較

タスク特性から最適解を選ぶフローチャート

タスクを複数の作業に分割する必要がある？
├─ No → サブエージェント（単一セッションで完結）
└─ Yes
    ├─ 作業間でリアルタイムの通信が必要？
    │   ├─ No → /batch（独立並列実行で十分）
    │   └─ Yes → Agent Teams（ピアツーピア協調）
    └─ 外部プログラムから制御したい？
        └─ Yes → Agent SDK

シンプルな判断基準は「人間チームなら3人以上で分担し、かつ頻繁にSlackでやり取りするような規模か？」。Yesなら Agent Teams、Noならサブエージェントか/batchで十分だ。

トークンコストと最適化テクニック

実測感覚：各teammateが独立コンテキストを持つ代償

各teammateが独立したコンテキストウィンドウを持つため、トークン消費はチームサイズにほぼ比例する。公式ドキュメントでは、Agent Teamsは通常セッションの3〜7倍程度のトークンを消費するとされている。

コスト削減の実践的アプローチ

• teammateにはSonnetを使う: 能力とコストのバランスが良い。Team leadだけOpusで判断させ、実作業はSonnetのteammatesに委譲するハイブリッド戦略が有効
• チームは小さく保つ: 2〜5人が推奨。1 teammateあたり5〜6タスクが生産性の目安
• broadcastの乱用を避ける: 全teammateのコンテキストにメッセージが追加されるため、本当に全員に伝える必要がある場合だけ使う
• spawn promptは簡潔に: teammatesはCLAUDE.mdやMCPサーバーを自動で読み込む。spawn promptに重複した情報を詰め込む必要はない
• 作業が終わったらチームをクリーンアップする: アイドル状態のteammateもトークンを消費し続ける

ハマりどころと対処法

ファイル競合とロック戦略

最も頻出する問題が同一ファイルへの同時書き込みだ。タスクのクレーム時にはファイルロックでrace conditionを防止する仕組みがあるが、ファイル編集自体の排他制御は完璧ではない。

対策は明快で、タスク設計の段階で担当ファイルをディレクトリレベルで分離することに尽きる。前述のクロスレイヤー協調パターンのように「backendはsrc/api/のみ、frontendはsrc/components/のみ」と明示するのが最も確実だ。

teammateの暴走・迷走を防ぐプロンプト設計

teammateがタスク完了を報告しない、または無限ループに陥るケースがある。対処法は以下の通り。

• タスクのスコープを狭くする: 「認証機能を全部作って」ではなく「ログインAPIエンドポイントを1つ作って」
• 完了条件を明示する: 「ビルドが通り、テストが全てパスしたら完了」
• plan approvalを要求する: teammateに計画を先に提出させ、Team leadが承認してから実装に移行させることで暴走を防ぐ

backendチームメイトを作成して、認証モジュールのリファクタリングを担当させて。
変更を加える前に、必ずプラン承認を要求すること。

また、現時点ではin-processモードのteammateに対して /resume や /rewind が未サポートだ。長時間タスクでの中断リスクに備え、タスク粒度を細かく保つことを推奨する。

まとめ — Agent Teamsを使うべきタイミング

全タスクにAgent Teamsを使う必要はない。単一ファイルの修正やコード生成ならサブエージェントで十分だし、独立したタスクの並列実行なら/batchの方がシンプルだ。

Agent Teamsが真価を発揮するのは、マイクロサービス横断のリファクタリング、複数仮説の並列検証、大規模機能のフロント・バック・テスト同時実装など、「人間チームなら3人以上で分担し、頻繁にコミュニケーションを取りながら進める」規模のタスクだ。

現時点では実験的機能だが、本記事で紹介した3つの設計パターンと判断フローは、アーキテクチャの本質を捉えたものだ。安定版がリリースされた後も、そのまま実戦に持ち込める知識になるはずだ。