Claude Code エージェントチーム完全ガイド｜セットアップから実践プロンプトまで

Claude Code Agent Teamsは、Anthropicが2026年2月にResearch Previewとして公開したマルチエージェント協調機能です。従来のTask Toolによるサブエージェントは呼び出し元に結果を返して終了する「ワンショット型」でしたが、Agent Teamsでは複数のClaude Codeプロセスが永続的なチームを形成し、双方向にメッセージをやり取りしながら同時進行で開発を進めます。

処理の高速化だけでなく、実装者とは別のエージェントがリアルタイムにコードを検査し、修正サイクルが人手なしで回り続ける自律的品質改善ループを構築できる点が、既存のAIコーディング支援と一線を画します。

アーキテクチャ：何がどう動くのか

Agent Teamsの内部は「指揮系統」「作業者」「進捗管理」「通信路」の4レイヤーで構成されています。

指揮レイヤー（チームリード） ユーザーが操作しているClaude Codeセッションそのものがリーダーとなります。TeamCreateを実行するとチーム定義ファイルが ~/.claude/teams/{team-name}/config.json に書き出され、同時にタスク管理用のディレクトリ ~/.claude/tasks/{team-name}/ が作られます。

実行レイヤー（チームメイト） リーダーがTask Toolで生成する独立プロセスです。それぞれが固有のコンテキストウィンドウを持ち、他メンバーの会話履歴は参照しません。モデルをメンバーごとに切り替えることも可能です（例：リーダーはOpus、メンバーはSonnet）。

進捗レイヤー（共有タスクリスト） TaskCreateで作成しTaskUpdateで状態遷移させるタスクが、全メンバーからTaskListで参照できます。ブロッキング依存（blockedBy）を設定すれば、前工程の完了を待ってから次工程が自動的に着手されます。

通信レイヤー（SendMessage） メンバー間のダイレクトメッセージ（type: "message"）と、全員への一斉送信（type: "broadcast"）の2経路があります。メッセージはキューイングされ、相手のターン終了後に自動配信されます。

Task Tool（サブエージェント）とどう違うのか

両者は「別プロセスでAIを動かす」点は共通していますが、設計思想が根本的に異なります。

観点	Task Tool（ワンショット型）	Agent Teams（永続チーム型）	判断の目安
プロセス生存期間	結果を返した時点で終了する	shutdown_requestを受けるまで動作し続ける	追加指示が発生するか？
対話の方向	呼び出し元→子の一方向	任意のメンバー同士で双方向	メンバー間で情報共有が必要か？
作業の割り当て	呼び出し時にプロンプトで固定	TaskListから空きタスクを自律的にピックアップ	タスク量が可変か？
文脈の引き継ぎ	毎回ゼロからスタート	メンバー内ではターンをまたいで蓄積	過去の調査結果を再利用するか？
フィードバックループ	結果に不満なら別プロセスを再生成	同一メンバーに追加指示を送信できる	反復改善が必要か？
API消費量	控えめ（要約のみ親に返却）	大きい（メンバーごとに独立コンテキスト）	予算上限はあるか？

選定フロー： 「grepでファイルを探す」「CSVをJSONに変換する」のような入力→出力が1回で決まる処理にはTask Toolで十分です。「設計→実装→テスト→レビュー→修正」のように工程が連鎖し、途中で仕様が変わりうる作業ではAgent Teamsが適しています。

セットアップ手順

Agent Teamsは2026年2月時点でResearch Previewのため、明示的なフラグ設定が必要です。

ステップ1：tmuxを導入する

メンバーの作業状況を個別ペインでリアルタイム表示するにはtmuxが必要です（in-processモードなら不要）。

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# インストール確認
tmux -V

ステップ2：設定ファイルでフラグを有効化する

~/.claude/settings.json に以下のブロックを追記します。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}

特定のプロジェクトだけで使いたい場合は、プロジェクトルートの .claude/settings.json に同じ内容を書きます。

teammateModeの3つの選択肢

teammateModeの値によってメンバーの表示方法が変わります。

"auto"（デフォルト） — tmuxセッション内で実行しているかを自動判定し、tmuxがあればペイン分割、なければin-processにフォールバックします
"in-process" — メンバーの出力がすべてメインターミナルにインラインで流れます。tmux不要ですが、複数メンバーの出力が混在して読みにくくなります
"tmux" — メンバーごとに専用のtmuxペインが生成され、作業経過がリアルタイムで並列表示されます。メンバー数が多い大規模開発に向いています

tmuxモードはVS Code統合ターミナル・Windows Terminal・Ghosttyでは正常に描画されません。macOS標準ターミナルまたはiTerm2から起動してください。

ステップ3：tmuxセッションを開始してClaude Codeを立ち上げる

# プロジェクトディレクトリに移動
cd your-project

# tmuxセッションを作成
tmux new -s dev-team

# Claude Codeを起動
claude

ステップ4：自然言語でチームを編成する

Claude Codeのプロンプトに、メンバー構成と各自の担当を記述するだけでチームが立ち上がります。

エージェントチームを作成して、以下のメンバーで src/auth モジュールのリファクタリングを行ってください。

- architect：設計方針の策定とコードレビュー
- implementer：実装担当
- tester：テスト作成と品質検証

この指示を受けたリードは内部でTeamCreate→メンバーのスポーン→タスク配分を自動実行します。tmuxモードを選択していれば、ターミナルが分割され各メンバーの進捗がライブ表示されます。

用途別プロンプトテンプレート

チーム編成は自然言語で指示できますが、メンバーの役割分担とコミュニケーションルールを明記するほど安定した出力が得られます。以下は実案件で効果が高かったパターンです。

パターン1：並列コードレビュー

エージェントチームを作成してください。
PRの内容をレビューします。

メンバー:
- security-reviewer：セキュリティ観点（認証・認可・入力検証・SQLインジェクション）
- performance-reviewer：パフォーマンス観点（N+1クエリ・不要な再レンダリング・メモリリーク）
- architecture-reviewer：設計観点（SOLID原則・責務分離・テスタビリティ）

対象: gh pr view 123 の差分を取得して分析してください。
各レビュアーは指摘事項を重大度（Critical/Major/Minor）で分類し、
最終的にリードが統合レポートを作成してください。

パターン2：フロントエンド＋バックエンド同時開発

エージェントチームを作成して、ユーザープロフィール編集機能を実装してください。

メンバー:
- backend：API設計とサーバーサイド実装（src/api/）
- frontend：UIコンポーネント実装（src/components/）
- qa：E2Eテスト作成（tests/e2e/）

注意:
- backendがAPI仕様を決めたら、frontendにSendMessageで共有すること
- 同じファイルを同時に編集しないこと
- qaはbackendとfrontendの両方が完了してからテストを開始すること

パターン3：競合仮説バグ調査

本番環境でユーザーログインが断続的に失敗する問題を調査してください。
エージェントチームを作成し、複数の仮説を並行で検証します。

メンバー:
- hypothesis-a：セッションストアの接続タイムアウトを調査（Redis関連のログとconfig）
- hypothesis-b：認証トークンの有効期限と更新ロジックを調査（src/auth/token.ts）
- hypothesis-c：ロードバランサーのスティッキーセッション設定を調査（nginx.conf, k8s ingress）

各メンバーは調査結果と根拠を報告し、リードが最も可能性の高い原因を特定してください。

パターン4：ドキュメント＋コード同時整備

エージェントチームで公開APIのドキュメントを整備してください。

メンバー:
- code-reader：ソースコードからAPIのエンドポイント一覧・パラメータ・レスポンス形式を抽出
- doc-writer：抽出された情報をもとにOpenAPI仕様書を作成（docs/api.yaml）
- example-maker：各エンドポイントのcurlコマンド例を作成（docs/examples.md）

code-readerが情報を抽出したら、doc-writerとexample-makerに共有してください。

稼働中のチームを操作する

個別メンバーへの指示送信

チーム稼働中に Shift+Up または Shift+Down を押すと、メッセージの送信先が切り替わります。デフォルトの送信先はリーダー自身ですが、キーを押すたびに次のメンバーへフォーカスが移動します。送信先が切り替わった状態でプロンプトを入力すると、そのメンバーに直接メッセージが届きます。

@architect このモジュールの依存関係を図にまとめてくれませんか

リーダーを調整専任にする（delegateモード）

デフォルトではリーダーも自らコードを書こうとするため、メンバーとの作業重複が発生しやすくなります。delegateモードを指示すると、リーダーはタスクの分割・割り当て・進捗監視に専念し、ファイル編集はすべてメンバーに移譲します。

delegateモードで作業してください。あなたは調整役に専念し、
実装はすべてチームメイトに任せてください。

実装前にプランの承認を挟む

メンバーがExitPlanModeを呼び出すと、リーダーに承認リクエストが飛びます。リーダーがplan_approval_responseで承認するまでメンバーは実装フェーズに進めません。大規模変更や破壊的操作を含むタスクで有効です。

CLAUDE.mdでチーム全員のルールを統一する

CLAUDE.mdはClaude Codeがセッション開始時に自動読み込みする設定ファイルです。Agent Teamsでは全メンバーのコンテキストに注入されるため、ここにコーディング規約やディレクトリ構成を書いておけば、メンバーごとに個別指示する手間が省けます。

# CLAUDE.md

## チーム開発ルール
- ファイル変更前に必ずgit statusで状態確認
- テスト追加なしの機能実装は不可
- 型安全を徹底（any型禁止）
- 同一ファイルの同時編集禁止：編集前にSendMessageで他メンバーに通知

## アーキテクチャ
- src/api/ - APIルート
- src/services/ - ビジネスロジック
- src/repositories/ - データアクセス
- tests/ - テストコード

トークンコストの構造と削減テクニック

Agent Teamsではメンバーごとにコンテキストウィンドウが確保されるため、API消費量はTask Toolの数倍になりえます。コスト構造を正しく把握したうえで最適化することが重要です。

なぜコストが膨らむのか

メンバー数 × 入力トークン — 全メンバーがCLAUDE.mdやシステムプロンプトを個別に読み込みます
メッセージ交換のオーバーヘッド — SendMessageの送受信でそれぞれトークンを消費します
broadcastの乗数効果 — 全員宛ての一斉送信はメンバー数だけ重複消費されます

実践的な削減アプローチ

メンバー数は2〜4人に絞る — 5人以上に増やしても並列化のリターンは逓減し、メッセージの輻輳でかえって遅くなることがあります
メンバーのモデルをSonnet 4.5に下げる — リーダーだけOpus 4.6を使い、コード実装や検索を担当するメンバーにはSonnetを割り当てるとコストが大幅に下がります。プロンプトにmodel: "sonnet"と指定するだけで切り替わります
broadcastを避け、個別messageを基本にする — 全員が知るべき情報は稀です。宛先を絞ることで不要なトークン消費を防げます
作業が終わったメンバーは即座にshutdown_requestで停止する — アイドル状態でもコンテキスト保持のコストは発生します
delegateモードでリーダーの実装を抑止する — リーダーが自分でコードを書き始めると、メンバーとの重複作業でトークンが無駄になります

エージェントチームを作成してください。
チームメイトはSonnetモデルを使用してください。

よくあるトラブルと対処法

メンバーが生成されずエラーになる

原因の大半はフラグの設定漏れです。~/.claude/settings.json内のCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSが文字列"1"になっているか再確認してください。settings.jsonを変更せずに一時的に試すなら環境変数で渡す方法もあります。

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

メンバーが操作のたびに承認ダイアログを出す

メンバーの権限レベルがデフォルト（確認あり）になっています。プロジェクトの.claude/settings.jsonでallowedToolsを定義するか、スポーン時にmode: "bypassPermissions"を指定するとダイアログを減らせます。

メンバーがクラッシュして応答しなくなる

リーダーにはメンバーのエラー通知が自動配信されます。リーダーが別のメンバーを新たにスポーンし、中断したタスクのオーナーを付け替えれば作業を引き継げます。

リーダーのセッションが不意に終了した

リーダーが落ちるとメンバーは送信先を失い孤立します。tmuxのセッション自体は残るため、以下のコマンドで後始末が必要です。

# 残存セッションの一覧
tmux list-sessions

# 不要なセッションを終了
tmux kill-session -t dev-team

競合ツールとの位置づけ

2026年2月現在、AIコーディングアシスタントで「複数エージェントが互いにメッセージを交換して協調作業する」機能を持つのはClaude Code Agent Teamsのみです。GitHub Copilot WorkspaceやCursor Composerは高度なコード生成能力を持ちますが、いずれも単一エージェントが逐次処理する設計であり、「実装エージェントにレビューエージェントがフィードバックを返し、修正サイクルが自律的に回る」ような構造は実現できません。

Agent Teamsが特に強みを発揮するのは、人間が介在しなくてもフィードバックループが回るシナリオです。たとえばテスト担当のメンバーが失敗テストの詳細を実装担当に直接送り、修正後に再テストが自動で走るフローは、単一エージェント型のツールでは手動トリガーが必要になります。

現時点の制約と注意点

Research Previewであるため、内部APIやツール名が予告なく変更される可能性があります。プロダクション運用には向きません
メンバー間でコンテキストウィンドウは分離されています。リーダーとの過去の対話をメンバーが参照することはできないため、必要な情報はSendMessageかタスクのdescriptionで明示的に渡す必要があります
複数メンバーが同一ファイルを同時編集するとコンフリクトが起きます。CLAUDE.mdにディレクトリ担当を明記するか、プロンプトでファイルロックのルールを指示してください
in-processモードでは全メンバーの出力が1つのターミナルに混在し、どのメンバーがどの作業をしているか判別しにくくなります
VS Code・JetBrainsの組み込みターミナルではtmuxのペイン分割が正しくレンダリングされないため、外部ターミナルで起動する必要があります

まとめ

Agent Teamsの核心は「AIエージェントが互いに対話し、自律的にフィードバックループを回す」点にあります。単一エージェントでは実現できなかった設計→実装→レビュー→修正の連鎖を、人間の介入を最小化しつつ並列に実行できます。

最短の導入ステップは3つです。

settings.jsonのenvブロックに "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" を追記
tmux new -s dev-team でセッションを作り、その中でclaudeを起動
プロンプトでメンバー構成と役割を指示

ワンショットで完結する調査・変換タスクには従来のTask Tool、工程が連鎖し途中でフィードバックが必要な開発タスクにはAgent Teamsという使い分けが基本になります。メンバーのモデルをSonnetに下げる、broadcastを避けるなどの最適化を組み合わせれば、コスト増を実用的な範囲に収められます。

公式ドキュメント: https://code.claude.com/docs/ja/agent-teams

アーキテクチャ：何がどう動くのか#

Task Tool（サブエージェント）とどう違うのか#

セットアップ手順#

ステップ1：tmuxを導入する#

ステップ2：設定ファイルでフラグを有効化する#

teammateModeの3つの選択肢#

ステップ3：tmuxセッションを開始してClaude Codeを立ち上げる#

ステップ4：自然言語でチームを編成する#

用途別プロンプトテンプレート#

パターン1：並列コードレビュー#

パターン2：フロントエンド＋バックエンド同時開発#

パターン3：競合仮説バグ調査#

パターン4：ドキュメント＋コード同時整備#

稼働中のチームを操作する#

個別メンバーへの指示送信#

リーダーを調整専任にする（delegateモード）#

実装前にプランの承認を挟む#

CLAUDE.mdでチーム全員のルールを統一する#

トークンコストの構造と削減テクニック#

なぜコストが膨らむのか#

実践的な削減アプローチ#

よくあるトラブルと対処法#

メンバーが生成されずエラーになる#

メンバーが操作のたびに承認ダイアログを出す#

メンバーがクラッシュして応答しなくなる#

リーダーのセッションが不意に終了した#

競合ツールとの位置づけ#

現時点の制約と注意点#

まとめ#