team-orchestration

チームオーケストレーション

概要

Agent Teams を使うと、複数の Claude Code セッションが、直接のピアツーピアメッセージと共有タスクリストを使って、同じプロジェクトで連携できます。サブエージェントとは異なり、チームメイト同士でやり取りし、タスクを動的に引き受け、共有課題について調整できます。

基本原則： 単に並列化するのではなく、連携によって成果が高まるタスクでチームを編成してください。チームメイト同士がメッセージをやり取りする必要がない場合は、代わりに並列サブエージェントを使ってください。

例外なし。回避策なし。近道なし。

最優先指令

NO TEAM WITHOUT A COLLABORATION REQUIREMENT

チームメイト同士でメッセージをやり取りしないなら、チームは必要ありません。

使用するタイミング

digraph when_teams {
    "Multiple tasks?" [shape=diamond];
    "Need peer-to-peer collaboration?" [shape=diamond];
    "Tasks independent?" [shape=diamond];
    "Agent Teams" [shape=box style=filled fillcolor=lightgreen];
    "parallel-execution" [shape=box];
    "delegated-execution" [shape=box];
    "Single agent" [shape=box];

    "Multiple tasks?" -> "Need peer-to-peer collaboration?" [label="yes"];
    "Multiple tasks?" -> "Single agent" [label="no"];
    "Need peer-to-peer collaboration?" -> "Agent Teams" [label="yes - teammates must share discoveries"];
    "Need peer-to-peer collaboration?" -> "Tasks independent?" [label="no"];
    "Tasks independent?" -> "parallel-execution" [label="yes - fire and forget"];
    "Tasks independent?" -> "delegated-execution" [label="no - sequential"];
}

チームを編成する場合：

• ある調査で得た発見が、別の調査の方向性を変えるような並列調査
• フロントエンド、バックエンド、テストの連携が必要な複数モジュールにまたがる機能
• インターフェースの調整が必要な複数レイヤーにまたがる変更
• 競合する仮説を検証するため、証拠の共有が必要なデバッグ
• 共通の規約を適用する、複数のサブシステムにまたがる大規模なリファクタリング

使用しない場合：

• 単純で独立したタスク（godmode:parallel-execution を使用）
• 逐次的な依存関係があるタスク（godmode:delegated-execution を使用）
• 単一ファイルまたは単一モジュールの変更
• Agent Teams 機能が有効になっていない場合
• 真に連携が必要なタスクが2件未満の場合

前提条件

Agent Teams は実験的な機能です。有効にする必要があります。

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true

これが有効でない場合、TeamCreate、TaskCreate、SendMessage ツールは使用できません。

遅延ツール： TeamCreate、TaskCreate、TaskUpdate、TaskGet、TaskList、SendMessage、EnterWorktree は遅延ツールです。初めて使用する前に、ToolSearch で読み込む必要があります。

// Load all team tools at once
ToolSearch: { "query": "select:SendMessage,TaskCreate,TaskUpdate,TaskList,TaskGet,EnterWorktree" }

開始プロトコル

BEFORE forming a team:

1. ENUMERATE: What are all the tasks?
2. MAP: Which tasks need information from other tasks?
3. COUNT: How many task pairs require shared discoveries?
4. DECIDE:
   - 0 pairs need collaboration -> Use parallel-execution
   - 1 pair needs collaboration -> Consider single agent or subagents
   - 2+ pairs need collaboration -> Use Agent Teams
5. ONLY THEN: Form the team

Skip any step = unnecessary team overhead

ワークフロー

ステップ 1：タスクとチームの適合性を評価する

TeamCreate を使う前に、次の質問に答えてください。

質問	はいの場合	いいえの場合
1つのエージェントで対応できますか？	代わりにそうしてください	続行
並列サブエージェントで対応できますか？	parallel-execution を使用	続行
作業中にエージェント同士で発見事項を共有する必要がありますか？	チーム	サブエージェント
エージェント同士でインターフェースを調整する必要がありますか？	チーム	サブエージェント
調整にかかるコストに見合う価値がありますか？	チーム	よりシンプルな方法

ステップ 2：チームを設計する

チームを作成してから、Agent ツールを使ってチームメイトを起動します。

// 1. Create the team
TeamCreate: {
  "team_name": "auth-refactor-team",
  "description": "Refactor authentication across API and frontend modules"
}

// 2. Spawn each teammate (2-5 max)
Agent: {
  "name": "backend-eng",
  "team_name": "auth-refactor-team",
  "prompt": "You are the backend engineer. Own all files in src/api/auth/. Implement the new token refresh flow. Coordinate with frontend-eng on the session interface.",
  "description": "Backend auth implementation",
  "mode": "bypassPermissions"
}

Agent: {
  "name": "frontend-eng",
  "team_name": "auth-refactor-team",
  "prompt": "You are the frontend engineer. Own all files in src/ui/auth/. Update login flow to use new token refresh. Coordinate with backend-eng on the session interface.",
  "description": "Frontend auth implementation",
  "mode": "bypassPermissions"
}

チームメイトの人数の目安：

人数	条件	調整コスト
2	インターフェースの合意が必要な、異なる2つのモジュール	低
3	フロントエンド＋バックエンド＋テスト、または独立した3つのサブシステム	中
4	4つのモジュールにまたがる横断的なリファクタリング	高
5	上限 — 真に大規模な作業に限る	非常に高

ステップ 2b：ワークスペースを分離する

ファイルシステム上のマージ競合を防ぐため、各チームメイトは独立した git worktree で作業してください。

// Called by each teammate at the start of their work
EnterWorktree: { "name": "auth-backend" }

EnterWorktree は個別の git worktree を作成するため、チームメイトは互いの作業を妨げずに並行してファイルを編集できます。チームリードは最後に godmode:merge-protocol を実行して worktree を統合します。

ステップ 3：明確な境界を設けてタスクを定義する

// Create tasks with clear scope and success criteria
TaskCreate: {
  "subject": "Implement token refresh endpoint",
  "description": "Build POST /api/auth/refresh that validates expired access tokens against refresh tokens. Return new access+refresh token pair. Files: src/api/auth/refresh.ts, src/api/auth/refresh.test.ts",
  "activeForm": "Implementing token refresh endpoint"
}

TaskCreate: {
  "subject": "Update login UI for token refresh",
  "description": "Update login flow to store refresh token and auto-refresh on 401. Files: src/ui/auth/login.tsx, src/ui/auth/session.ts",
  "activeForm": "Updating login UI for token refresh"
}

// Set up dependencies and assign owners
TaskUpdate: { "taskId": "2", "addBlockedBy": ["1"] }
TaskUpdate: { "taskId": "1", "owner": "backend-eng" }
TaskUpdate: { "taskId": "2", "owner": "frontend-eng" }

タスク設計のルール：

• スコープを明確にする：このチームメイトが担当するファイル／モジュールを正確に指定する
• 依存関係：先に完了する必要があるタスクには addBlockedBy を使用する
• 成功基準：説明に「完了」の条件を記載する
• ファイルの担当範囲：チームメイト間で重複させない（マージ競合を防ぐ）

ファイルの担当範囲は譲れません。 2人のチームメイトが同じファイルを編集すれば、マージ競合は避けられません。複数の観点から共有ファイルを変更する必要がある場合は、メッセージを通じて他のメンバーと調整する担当者を1人だけ割り当ててください。

ステップ 4：チームリードとして調整する

digraph team_lead_loop {
    "Check TaskList" [shape=box];
    "All tasks completed?" [shape=diamond];
    "Any teammate blocked?" [shape=diamond];
    "Send clarifying message" [shape=box];
    "Resolve dependency" [shape=box];
    "Integrate results" [shape=box style=filled fillcolor=lightgreen];

    "Check TaskList" -> "All tasks completed?";
    "All tasks completed?" -> "Integrate results" [label="yes"];
    "All tasks completed?" -> "Any teammate blocked?" [label="no"];
    "Any teammate blocked?" -> "Send clarifying message" [label="needs info"];
    "Any teammate blocked?" -> "Resolve dependency" [label="blocked by task"];
    "Any teammate blocked?" -> "Check TaskList" [label="no - working"];
    "Send clarifying message" -> "Check TaskList";
    "Resolve dependency" -> "Check TaskList";
}

チームリードとして、次のことを行います。

• TaskList を使ってタスクの完了状況を追跡する（パラメーターは不要です。呼び出すだけです）
• 直接メッセージを使って、チームメイト間で発見事項を伝達する：

// Direct message to relay a discovery
SendMessage: {
  "type": "message",
  "recipient": "frontend-eng",
  "content": "backend-eng finished the refresh endpoint. The response shape is { accessToken, refreshToken, expiresIn }. You can unblock now.",
  "summary": "Refresh endpoint contract ready"
}

• 前提タスクを完了済みにして、依存関係のブロックを解除する：

TaskUpdate: { "taskId": "1", "status": "completed" }

• チームメイト間で進め方について意見が分かれた場合は、調停する
• ブロードキャストは、チーム全体に関わる重大な問題に限って使用する（コストが高く、N件のメッセージを送信します）：

// Broadcast — use sparingly, sends N separate messages
SendMessage: {
  "type": "broadcast",
  "content": "Convention change: all auth endpoints now return camelCase keys",
  "summary": "Auth API convention change"
}

ステップ 5：結果を統合する

すべてのタスクが完了したら：

1. すべての変更をまとめて確認し、一貫性を保ちます
2. チームメイト間でファイルの競合がないことを確認します
3. テストスイート全体を実行します
4. モジュール間のインターフェースに不整合がないことを確認します
5. 必須のサブプロトコル： godmode:merge-protocol を使用します

チームのパターン

このディレクトリにある team-patterns.md で、次の 5 つのチームパターンを確認してください：

1. 調査チーム — 異なる観点を並行して調査します
2. 機能チーム — 複数モジュールの開発（フロントエンド＋バックエンド＋テスト）
3. 診断チーム — 複数の仮説を並行して検証します
4. レビュー担当チーム — 複数の観点からコードレビューを行います
5. 移行チーム — コードベース全体にわたる規約の変更を行います

各パターンには、使用するタイミング、チーム構成、タスク設計、連携の流れ、例が含まれます。

ツール一覧

ツール	目的	主なパラメーター	タイミング
TeamCreate	チームを編成する	team_name、description	開始時に 1 回
Agent	チームメイトを起動する	name、team_name、prompt、description、mode	チームメイトごとに 1 回
EnterWorktree	ワークスペースを分離する	name	各チームメイトの開始時
TaskCreate	タスクを追加する	subject、description、activeForm	セットアップ中
TaskList	すべてのタスクを表示する	(なし)	進捗確認
TaskGet	タスクの詳細を取得する	taskId	作業開始前
TaskUpdate	タスクの担当・完了・更新を行う	taskId、status、owner、addBlockedBy	作業全体を通じて
SendMessage	直接メッセージを送信する	type: "message"、recipient、content、summary	連携
SendMessage	全員にメッセージを送信する	type: "broadcast"、content、summary	重大な問題に限る
SendMessage	シャットダウンを依頼する	type: "shutdown_request"、recipient、content	終了時

チームメイトの動作：想定されること

チームメイトは独立した Claude セッションです。主な動作は次のとおりです。

• ターン間は待機状態になります — これは通常の動作です。チームメイトはメッセージやタスクを待つ間、待機状態になります。メッセージを受信するか、タスクが利用可能になると、再び動作します。
• タスクを担当します — チームメイトは作業を開始する前に、TaskUpdate を使って自分を担当者に設定します。
• 互いにメッセージを送信します — チームメイトはチームリードだけでなく、互いに直接メッセージを送信できますし、そうするべきです。
• 自律的に作業します — タスクを受け取ったチームメイトは、自律して作業します。過度な管理は避けてください。

認知上の落とし穴

正当化	実態
「チームは常にサブエージェントより優れている」	チームには連携のオーバーヘッドが伴います。協力が必要な場合に限り編成してください。
「チームメイトが多いほど、納品が速くなる」	チームメイトが増えるほど、連携も増えます。集中した 3 人のチームメイトは、分散した 6 人より高い成果を上げます。
「まずチームを編成して、タスクは後で考えよう」	チーム編成前にタスクを設計する必要があります。タスクがないと、チームメイトは待機しながらトークンを消費します。
「チームメイトはファイルを共有できる」	ファイルの共有はマージ競合につながります。担当範囲を明確にしてください。
「定期的な更新には全員への送信でよい」	全員への送信では N 件のメッセージが送られます。特定のチームメイトには SendMessage を使ってください。
「依存関係は暗黙にわかる」	依存関係が定義されていないと、チームメイト同士の作業が衝突します。

ガードレール

禁止事項：

• 単純なタスクでチームを編成すること（オーバーヘッドに見合いません）
• チームメイトが同じファイルを編集できるようにすること（マージ競合につながります）
• チームの作業完了後に統合レビューを省略すること
• チームメイトのメッセージを無視すること（そこには発見事項が含まれています）
• 5 人を超えるチームメイトでチームを編成すること（連携が急激に複雑になります）
• 定期的な更新に全員への送信を使うこと（直接メッセージを使ってください）
• タスクを明確に設計せずにチームを開始すること
• タスク間の依存関係を未定義のままにすること

必須事項：

• ファイルの担当範囲を明確に定義する
• blockedBy を使ってタスクの依存関係を設定する
• 完了後、すべての変更をまとめて確認する
• 統合後にテストスイート全体を実行する
• チームメイト同士の連携には SendMessage を使う
• タスクが完了したら完了としてマークする（チームメイトは TaskList で利用可能な作業を確認します）

ツール呼び出しリファレンス

Agent Teams のすべてのツールについて、パラメーターの仕様を網羅しています。これらをそのままコピーしてください。パラメーター名は正確に指定する必要があります。

TeamCreate

名前付きチームを作成します。チームメイトを起動する前に一度呼び出してください。

{
  "team_name": "feature-billing-team",
  "description": "Build subscription billing feature"
}

パラメーター	型	必須	備考
team_name	string	はい	ケバブケースの識別子
description	string	はい	チームの作業内容

Agent（チームメイトの起動）

既存のチームにチームメイトを起動します。各チームメイトは独立した Claude セッションです。

{
  "name": "backend-eng",
  "team_name": "feature-billing-team",
  "prompt": "You are the backend engineer on this team. Own src/api/billing/. Build the Stripe webhook handler and subscription CRUD endpoints. Use godmode:test-first for implementation. Coordinate with frontend-eng on API contracts via SendMessage.",
  "description": "Backend billing implementation",
  "mode": "bypassPermissions"
}

パラメーター	型	必須	備考
name	string	はい	チームメイトの識別子（SendMessage の recipient で使用）
team_name	string	はい	TeamCreate の team_name と一致させる必要があります
prompt	string	はい	ファイルの担当範囲、作業範囲、調整ルールを含む完全な指示
description	string	はい	UI に表示される短い説明
mode	string	いいえ	"bypassPermissions" を指定すると、チームメイトは権限の確認なしで作業できます

EnterWorktree

チームメイト用の隔離された git ワークツリーを作成します。複数のチームメイトが並行してファイルを編集する際の、ファイルシステムの競合を防ぎます。

{
  "name": "billing-feature"
}

パラメーター	型	必須	備考
name	string	はい	ワークツリーの識別子。ブランチ名／ディレクトリー名になります

TaskCreate

すべてのチームメイトから参照できる共有タスクリストにタスクを追加します。

{
  "subject": "Implement Stripe webhook handler",
  "description": "Build POST /webhooks/stripe endpoint that handles subscription.created, subscription.updated, and subscription.deleted events. Files: src/api/billing/webhooks.ts, src/api/billing/webhooks.test.ts",
  "activeForm": "Implementing Stripe webhook handler"
}

パラメーター	型	必須	備考
subject	string	はい	命令形のタイトル（例：「認証バグを修正する」）
description	string	はい	作業範囲、ファイル一覧、受け入れ基準の全体
activeForm	string	いいえ	スピナーに表示する現在進行形の文（例：「認証バグを修正中」）

TaskUpdate

タスクのステータス、担当者、または依存関係を更新します。タスクの引き受け、完了、ブロック関係の設定に使用します。

// Assign owner
{ "taskId": "1", "owner": "backend-eng" }

// Set dependency — task 3 cannot start until tasks 1 and 2 complete
{ "taskId": "3", "addBlockedBy": ["1", "2"] }

// Mark in progress
{ "taskId": "1", "status": "in_progress" }

// Mark complete
{ "taskId": "1", "status": "completed" }

パラメーター	型	必須	備考
taskId	string	はい	TaskCreate／TaskList で取得したタスク ID
status	string	いいえ	"pending"、"in_progress"、"completed"、または "deleted"
owner	string	いいえ	割り当てるチームメイト名
addBlockedBy	string[]	いいえ	このタスクより先に完了する必要があるタスク ID
addBlocks	string[]	いいえ	このタスクがブロックするタスク ID
subject	string	いいえ	更新後のタイトル
description	string	いいえ	更新後の説明
activeForm	string	いいえ	更新後のスピナー表示テキスト

TaskList

すべてのタスクについて、ステータス、担当者、ブロック関係の情報を返します。パラメーターはありません。

// No parameters — just call it
TaskList: {}

TaskGet

指定したタスクの詳細を取得します。

{ "taskId": "1" }

パラメーター	型	必須	備考
taskId	string	はい	取得するタスク ID

SendMessage

チーム内のコミュニケーションに使用する3種類のメッセージです。

ダイレクトメッセージ（デフォルト。ほとんどのコミュニケーションで使用します）：

{
  "type": "message",
  "recipient": "backend-eng",
  "content": "The profile API needs a PUT /profile/preferences endpoint. Frontend needs to update preferences without replacing the full profile.",
  "summary": "API contract update request"
}

ブロードキャスト（すべてのチームメイトに送信。必要な場合にのみ使用します）：

{
  "type": "broadcast",
  "content": "Convention change: all API responses now use camelCase keys",
  "summary": "API convention change"
}

シャットダウンリクエスト（チームメイトを正常にシャットダウンします）：

{
  "type": "shutdown_request",
  "recipient": "backend-eng",
  "content": "All tasks complete, wrapping up"
}

パラメーター	型	必須	備考
type	string	はい	"message"、"broadcast"、または "shutdown_request"
recipient	string	message／shutdown の場合	チームメイト名
content	string	はい	メッセージ本文
summary	string	message／broadcast の場合	UI に表示される5～10語のプレビュー

チーム設定の完全な例

2人の機能チームを設定する最初から最後までの例：

// 1. Create team
TeamCreate: { "team_name": "billing-team", "description": "Build subscription billing" }

// 2. Create tasks
TaskCreate: {
  "subject": "Build Stripe webhook handler",
  "description": "POST /webhooks/stripe handling subscription events. Files: src/api/billing/webhooks.ts",
  "activeForm": "Building Stripe webhook handler"
}
TaskCreate: {
  "subject": "Build billing dashboard UI",
  "description": "Subscription management page showing plan, usage, invoices. Files: src/ui/billing/",
  "activeForm": "Building billing dashboard"
}

// 3. Wire dependencies and assign owners
TaskUpdate: { "taskId": "2", "addBlockedBy": ["1"] }
TaskUpdate: { "taskId": "1", "owner": "backend-eng" }
TaskUpdate: { "taskId": "2", "owner": "frontend-eng" }

// 4. Spawn teammates (they auto-claim their assigned tasks)
Agent: {
  "name": "backend-eng",
  "team_name": "billing-team",
  "prompt": "You are the backend engineer. Own src/api/billing/. Start with task #1. Use EnterWorktree to isolate your workspace. Use godmode:test-first. Message frontend-eng with the API contract when done.",
  "description": "Backend billing implementation",
  "mode": "bypassPermissions"
}
Agent: {
  "name": "frontend-eng",
  "team_name": "billing-team",
  "prompt": "You are the frontend engineer. Own src/ui/billing/. Task #2 is blocked by #1. Wait for backend-eng to share the API contract, then implement. Use EnterWorktree to isolate your workspace.",
  "description": "Frontend billing implementation",
  "mode": "bypassPermissions"
}

// 5. Monitor as team lead
TaskList: {}

// 6. When all tasks complete, shutdown teammates
SendMessage: { "type": "shutdown_request", "recipient": "backend-eng", "content": "All done, wrapping up" }
SendMessage: { "type": "shutdown_request", "recipient": "frontend-eng", "content": "All done, wrapping up" }

統合

関連するオーケストレーションプロトコル：

• godmode:parallel-execution — 協力が不要な独立タスク向け
• godmode:delegated-execution — レビューチェックポイントを設ける逐次タスク向け
• godmode:task-runner — 別のセッションで計画を実行する場合

チームメイトは次を使用してください：

• godmode:test-first — 実装タスク向け
• godmode:fault-diagnosis — 診断チームの調査向け
• godmode:completion-gate — タスクを完了としてマークする前

完了に必須：

• godmode:merge-protocol — チームの全タスク完了後