agent-teams

エージェントチーム

共有タスクリスト、エージェント間メッセージング、独立したコンテキストウィンドウを利用して、複数の Claude Code インスタンスをチームとして連携させます。サブエージェント（Task ツール）とは根本的に異なり、チームメイト同士が呼び出し元に報告するだけでなく、直接やり取りします。

エージェントチームとサブエージェントの使い分け

Does the work require inter-agent communication?
├── No → Use subagents (Task tool)
│   ├── Focused tasks where only the result matters
│   ├── Research/verification that reports back
│   └── Lower token cost (results summarized to main context)
└── Yes → Use Agent Teams
    ├── Teammates need to share findings mid-task
    ├── Adversarial debate / competing hypotheses
    ├── Self-organizing work from shared task list
    └── Complex coordination across 3+ parallel workers

How many parallel workers?
├── 1-3 independent tasks → Subagents (less overhead)
├── 3-5 coordinating workers → Agent Teams
└── 5+ workers → Agent Teams with delegate mode

特に適した用途：

• 複数の視点による調査とレビューを同時に行う
• チームメイトがそれぞれ異なるファイルを担当する複数モジュールの機能
• 仮説を競わせるデバッグ（対立的な調査）
• レイヤーをまたぐ連携（フロントエンド、バックエンド、テスト）

避けるべきケース：

• 依存関係の多い逐次的なタスク
• 同じファイルの編集（上書きが発生します）
• 単純で範囲が明確な作業（連携のオーバーヘッドに見合いません）
• 定型的なタスク（単一セッションのほうが費用対効果に優れています）

環境設定

エージェントチームを有効にします（実験的機能で、デフォルトでは無効です）。

// settings.json (user or project level)
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

またはシェルで設定します：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

ツールのアーキテクチャ

エージェントチームでは、単一の「TeammateTool」ではなく、4つの異なるツールを使用します。

ツール	用途
TeamCreate	チーム設定とタスクディレクトリを作成します。呼び出し元がリーダーになります
SendMessage	すべてのエージェント間通信に使用します（以下の5種類のメッセージ）
TeamDelete	シャットダウン後にチームのリソースを削除します（クリーンアップ）
Task（拡張）	name と team_name パラメーターが指定されている場合、チームメイトを起動します

SendMessage の種類

種類	パラメーター	説明
message	recipient、content、summary	1人のチームメイトへのダイレクトメッセージ
broadcast	content、summary	すべてのチームメイトへのメッセージ（コストが高くなります。N件の配信が発生します）
shutdown_request	recipient、content	チームメイトの終了を要求します（リーダーのみ）
shutdown_response	request_id、approve、content	終了を承認または拒否します（チームメイトのみ）
plan_approval_response	request_id、approve、recipient、content	計画を承認または拒否します（リーダーのみ）

重要： 通常のテキスト出力はチームメイトには表示されません。エージェント間の通信には、必ず SendMessage を使用してください。

使用上の注意：

• broadcast より message を優先してください。broadcast では、チームメイトがN人いるとN件のメッセージが作成されます
• メッセージは受信者の受信トレイに自動的に配信されます（ポーリングは不要です）
• チームメイトが作業を終えると、アイドル通知が自動的に送信されます
• TeamDelete を実行するのはリーダーのみにしてください。チームメイトのコンテキストでは正しく解決されないことがあります

チームメイトの起動

方法1：自然言語 — Claude にチームの作成を依頼し、構成を説明します。

Create an agent team to review this PR. Spawn three reviewers:
- One focused on security
- One checking performance
- One validating test coverage

方法2：チームパラメーターを指定して Task ツールを使用する：

Task({
  team_name: "my-team",
  name: "worker-1",
  subagent_type: "general-purpose",
  prompt: "Review src/auth/ for security vulnerabilities...",
  model: "sonnet",
  run_in_background: true
})

起動時にチームメイトが受け取るもの：

• 通常のセッションと同じプロジェクトコンテキスト（CLAUDE.md、MCP サーバー、スキル）
• リーダーからの起動プロンプト
• リーダーの会話履歴は引き継がれません

チームメイト向けの組み込みエージェントタイプ：

タイプ	機能
general-purpose	すべてのツール（Edit、Write、Bash、Task など）
Explore	読み取り専用 — コードベースの検索と分析
Plan	読み取り専用 — アーキテクチャ設計
Bash	システムコマンドのみ

モデルの選択： ほとんどのチームメイトには、コスト効率の高い Sonnet を使用してください。リーダーまたは複雑な推論タスクには Opus を選んでください。model パラメーター、または自然言語（「各チームメイトに Sonnet を使用してください」など）で指定します。

起動バックエンド

チームメイトの表示方法を制御します。settings.json の teammateMode、または CLI フラグ --teammate-mode で設定します。

モード	設定	要件	動作
自動（デフォルト）	"auto"	なし	tmux 内ではペインを分割し、それ以外ではインプロセスで動作します
インプロセス	"in-process"	なし	メインターミナル内にすべて表示します。Shift+Up/Down で選択します
ペイン分割	"tmux"	tmux または iTerm2	各チームメイトに専用のペインが割り当てられます

// settings.json
{ "teammateMode": "in-process" }

# CLI override for single session
claude --teammate-mode in-process

自動検出のロジック：

1. $TMUX 環境変数が設定されている → tmux の分割ペインを使用します
2. $ITERM_SESSION_ID が設定されており、it2 が利用可能 → iTerm2 を使用します
3. which tmux が成功する → tmux を使用します
4. フォールバック → インプロセス

インプロセスでの操作：

• Shift+Up/Down → チームメイトを選択します
• Enter → チームメイトのセッションを表示します
• Escape → チームメイトの現在のターンを中断します
• Ctrl+T → タスクリストを切り替えます

分割ペインでの操作：

• ペインをクリックすると、直接操作できます
• 各チームメイトに完全なターミナル画面が割り当てられます

通信パターン

ダイレクトメッセージ（type: "message"）： SendMessage を介して、特定のチームメイト 1 人に送信します。対象を絞った指示、フォローアップ、または方針の変更に使用します。

ブロードキャスト（type: "broadcast"）： SendMessage を介して、すべてのチームメイトに同時に送信します。チームの規模に応じてコストが増加するため、必要な場合にのみ使用してください。共有する決定事項の告知や、進捗状況の報告依頼に適しています。

自動配信： メッセージは受信者に自動的に届きます。リードが進捗を確認するためにポーリングする必要はありません。

アイドル通知： チームメイトが作業を終えて停止すると、自動的にリードに通知します。

メッセージ型のスキーマ： assets/message-formats.yml を参照してください。

タスクの調整

共有タスクリストで、チーム全体の作業を調整します。すべてのエージェントがタスクの状態を確認でき、着手可能な作業を担当できます。

タスクのライフサイクル： pending → in_progress → completed

割り当てパターン：

• リードが明示的に割り当てる（「タスク 3 をセキュリティレビュー担当に割り当ててください」）
• 自己割り当て：タスクを終えたチームメイトが、次に未割り当てでブロックされていないタスクを選びます

依存関係：

• blockedBy フィールド（タスク ID の配列）で指定します
• 自動ブロック解除：ブロック元のタスクが完了すると、ブロックされていたタスクが着手可能になります
• ポーリングなしで順次処理のパイプラインを実現できます

ファイルロック： タスクの担当取得にはファイルロックを使用し、複数のチームメイトが同時に担当しようとした際の競合状態を防ぎます。

推奨するタスクの規模：

• 安定した処理量を確保するには、チームメイト 1 人あたり 5～6 タスク
• 明確な成果物を生み出す、自己完結した単位
• 避けるべきもの：小さすぎるタスク（メリットよりオーバーヘッドが大きい）や大きすぎるタスク（労力が無駄になるリスクがある）

委任モード

リードが使用できるツールを、調整専用（起動、メッセージ送信、チームメイトのシャットダウン、タスク管理）に制限します。リード自身がタスクを実装するのを防ぎます。

有効化： チームの起動後に Shift+Tab を押して、委任モードに切り替えます。

使用する場面：

• リードがチームメイトを待たずにタスクを実装し続けてしまう
• 純粋なオーケストレーション（作業の分割、割り当て、成果の統合）に専念したい
• リードが調整に集中すべき大規模なチーム

既知のバグ： 委任モードに入った後に起動したチームメイトは、制限されたツールアクセスを引き継ぎます（Read、Write、Edit、Bash、Glob、Grep を利用できなくなります）。回避策： Shift+Tab を押す前に、すべてのチームメイトを起動してください。

使用を避ける場面：

• リードも実装に参加できる小規模なチーム
• リードがファイル編集を必要とする統合作業を行う必要がある

プラン承認ワークフロー

チームメイトが実装前に計画を立てるようにします。リードが承認するまで、チームメイトは読み取り専用のプランモードで作業します。

プラン承認を有効にして起動する：

Spawn an architect teammate to refactor the auth module.
Require plan approval before they make any changes.

チーム設定の planModeRequired フィールドで、メンバーごとにこの設定を制御します。

ワークフロー：

1. Teammate spawned with planModeRequired: true
2. Teammate explores codebase, creates plan
3. Teammate sends plan_approval_request to lead
4. Lead reviews plan:
   ├── approvePlan → teammate exits plan mode, begins implementation
   └── rejectPlan(feedback) → teammate stays in plan mode, revises
5. Cycle repeats until approved

プロンプトで承認基準に影響を与える：

Only approve plans that include test coverage.
Reject plans that modify the database schema.

ファイル競合の回避

2 人のチームメイトが同じファイルを編集すると、変更が上書きされます。ファイルの担当を割り当てて防止します。

- teammate-1: owns src/api/ files
- teammate-2: owns src/ui/ files
- teammate-3: owns tests/ files

アンチパターン： 複数のチームメイトが、共有の設定ファイル、package.json、またはマイグレーションファイルを同時に変更すること。

対策： タスクの依存関係を使用して、共有ファイルの編集を順次実行します。

フックの統合

エージェントチームで品質ゲートを適用するための2つのフックイベントです。

TeammateIdle

チームメイトが作業ターンを終え、アイドル状態になる直前に発生します。

• 終了コード 0 → アイドル状態への移行を許可します
• 終了コード 2 → 作業を続行します（stderr がフィードバックとしてチームメイトに渡されます）
• マッチャーには対応していません（発生するたびに実行されます）
• 入力に含まれる項目：teammate_name、team_name

TaskCompleted

タスクが完了としてマークされるときに発生します（TaskUpdate 経由、またはチームメイトが進行中のタスクを残したまま作業を終えたとき）。

• 終了コード 0 → 完了を許可します
• 終了コード 2 → 完了を阻止します（stderr がフィードバックとして渡されます）
• マッチャーには対応していません（発生するたびに実行されます）
• 入力に含まれる項目：task_id、task_subject、task_description、teammate_name、team_name

TeammateIdle： コマンドフックのみ対応しています（プロンプト／エージェントフックには対応していません）。TaskCompleted： コマンド、プロンプト、エージェントのハンドラータイプに対応しています。

設定例については、assets/hook-examples.yml を参照してください。

グレースフルシャットダウン

シャットダウンの手順：

1. Lead sends requestShutdown to each teammate
2. Teammate receives request:
   ├── approveShutdown → finishes current request/tool call, terminates
   └── rejectShutdown(reason) → continues working
3. Wait for all teammates to terminate
4. Lead calls cleanup
   ├── If active teammates remain → cleanup fails
   └── If all terminated → removes team config + task directories

重要：

• シャットダウンには時間がかかる場合があります。チームメイトは終了する前に、現在のリクエストを完了します
• クリーンアップには必ずリードを使用してください（チームメイトは使用しないでください）
• 孤立した tmux セッションの場合：tmux ls && tmux kill-session -t <name>

権限

• チームメイトはリードの権限設定で起動します
• リードが --dangerously-skip-permissions を使用する場合、すべてのチームメイトも同様に使用します
• 起動後に個々のチームメイトのモードを変更できます
• 起動時にチームメイトごとのモードを設定することはできません
• 権限設定で一般的な操作を事前承認すると、プロンプトによる中断を減らせます

ファイル構成

~/.claude/
├── teams/
│   └── {team-name}/
│       ├── config.json          # team config (members, lead, settings)
│       └── inboxes/
│           └── {agent}.json     # per-agent message inbox
└── tasks/
    └── {team-name}/
        ├── 1.json               # task files (auto-incremented IDs)
        ├── 2.json
        └── N.json

スキーマの詳細については、assets/team-config-schema.yml を参照してください。

既知の制限事項

制限事項	影響	回避策
プロセス内チームメイトではセッションを再開できない	/resume と /rewind を実行してもチームメイトは復元されません	再開後に新しいチームメイトを起動するようリードに指示します
タスクのステータスが遅れることがある	チームメイトがタスクを完了としてマークしない場合があります	手動で更新するか、チームメイトに催促するようリードに伝えます
シャットダウンに時間がかかることがある	チームメイトは停止する前に、現在のリクエストを完了します	しばらく待つか、代わりのチームメイトを起動します
1セッションにつきチームは1つ	1人のリードから複数のチームを管理できません	新しいチームを開始する前に、現在のチームをクリーンアップします
入れ子のチームには対応していない	チームメイトは独自のチームを起動できません	チーム構成はリードのみが管理します
リードは固定	チームメイトを昇格させたり、リーダーシップを移譲したりできません	開始前にチーム構成を計画します
権限は起動時に設定される	すべてのチームメイトがリードの権限モードを継承します	起動後に個々のモードを変更します
分割ペインには tmux/iTerm2 が必要	VS Code terminal、Windows Terminal、Ghostty ではサポートされていません	代替手段としてプロセス内モードを使用します
ハートビートのタイムアウトは5分	非アクティブなチームメイトは自動的に非アクティブとしてマークされます	タスクを割り当ててチームメイトをアクティブに保ちます
ブロードキャストの負荷はチームメイト数に比例する	チームメイトが N 人の場合、メッセージは N 件送信されます	broadcast よりも宛先を指定する message を優先します
デリゲートモードでの起動に関するバグ	Shift+Tab の後に起動したチームメイトはファイルツールを使用できません	デリゲートモードに入る前に、すべてのチームメイトを起動します

エラー処理

エラー	原因	修正方法
"Cannot cleanup with active members"	チームメイトがまだ実行中です	まず、すべてのチームメイトに requestShutdown を実行します
"Already leading a team"	チームはすでに存在します	既存のチームに cleanup を実行するか、別の名前を使用します
"Agent not found"	チームメイトの名前または ID が間違っています	config.json で正しいエージェント ID を確認します
"Team does not exist"	チームが作成されていません	まず spawnTeam を実行します
チームメイトが表示されない	さまざまな原因が考えられます	Shift+Down で切り替えます。タスクの複雑さを確認し、tmux がインストールされていることを確認します
権限に関するプロンプトが多すぎる	チームメイトの権限確認がリードにも表示されます	設定で一般的な操作を事前承認します
作業完了前にリードがシャットダウンする	リードがチームの作業は完了したと判断しています	チームメイトの作業が終わるまで待つようリードに伝えます

オーケストレーションパターン

詳細な4つのパターンについては、references/orchestration-patterns.md を参照してください。

1. 並列レビュー — 複数の専門家が、それぞれ異なる観点から同時にレビューします
2. 競合する仮説 — 敵対的な調査によって、アンカリングバイアスを防ぎます
3. 複数モジュールにまたがる機能 — ファイルの担当範囲とタスクの依存関係を定め、実装を調整します
4. 調査パイプライン — 調査フェーズの成果を、計画承認後の実装に引き継ぎます