team-orchestration

团队编排

概述

Agent Teams 可让多个 Claude Code 会话在同一个项目中协作，并通过点对点消息和共享任务列表进行沟通。与子 Agent 不同，队友可以彼此沟通、动态认领任务，并协同解决问题。

核心原则： 只有当任务能从协作中受益时才组建团队，而不只是为了并行处理。如果队友之间无需互发消息，请改用并行子 Agent。

不例外。不绕过。不走捷径。

首要原则

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 前，请回答以下问题：

问题	如果是	如果否
单个 Agent 能处理这项任务吗？	改由单个 Agent 处理	继续
并行子 Agent 能处理这项任务吗？	使用 parallel-execution	继续
Agent 是否需要在工作过程中共享发现？	使用团队	使用子 Agent
Agent 是否需要协商接口？	使用团队	使用子 Agent
协调开销是否合理？	使用团队	采用更简单的方式

步骤 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	两个需要对齐接口的不同模块	低
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 来整合各个工作树。

步骤 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
• 成功标准：在描述中说明“完成”的标准
• 文件归属：队友之间不得有任何重叠（避免合并冲突）

文件归属不容妥协。 两位队友编辑同一个文件必然会导致合并冲突。如果同一文件需要从多个角度进行修改，请指定一位队友负责，并让其通过消息与其他人协调。

步骤 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，了解五种有文档说明的团队模式：

1. 探索团队 — 并行调查不同维度
2. 功能团队 — 多模块开发（前端 + 后端 + 测试）
3. 诊断团队 — 并发验证不同假设
4. 检查团队 — 从多个角度进行代码审查
5. 迁移团队 — 在整个代码库中更改通用约定

每种模式都包括：适用场景、团队结构、任务设计、协调流程和示例。

工具一览

工具	用途	关键参数	使用时机
TeamCreate	组建团队	team_name、description	开始时一次
Agent	启动队友	name、team_name、prompt、description、mode	每位队友一次
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 将任务分配给自己。
• 相互发送消息 — 队友可以且应该直接相互发送消息，而不只是联系团队负责人。
• 自主开展工作 — 分配任务后，队友会自主工作。避免事无巨细地管理。

思维陷阱

合理化借口	事实
“团队总是优于子 Agent”	团队会增加协调开销。只有在确实需要协作时才组建团队。
“队友越多 = 交付越快”	队友越多 = 协调越多。3 位专注的队友胜过 6 位各自分散的队友。
“我先组建团队，之后再考虑任务”	必须在组建团队前设计好任务。没有任务 = 队友空闲并消耗令牌。
“队友可以共享文件”	共享文件 = 合并冲突。明确分配文件所有权。
“日常更新也可以群发”	群发会发送 N 条消息。请使用 SendMessage 向特定队友发送消息。
“依赖关系不言自明”	未定义依赖关系 = 队友互相妨碍。

防护措施

禁止：

• 为简单任务组建团队（不值得增加开销）
• 允许队友编辑相同文件（会产生合并冲突）
• 团队完成后跳过整合审查
• 忽略队友消息（其中包含重要发现）
• 组建超过 5 位队友的团队（协调复杂度会急剧上升）
• 将群发用于日常更新（请使用私信）
• 未明确设计任务就启动团队
• 不定义任务之间的依赖关系

必须：

• 明确划分文件所有权边界
• 使用 blockedBy 设置任务依赖关系
• 完成后一起审查所有更改
• 整合后运行完整测试套件
• 使用 SendMessage 协调队友之间的沟通
• 完成任务后将其标记为已完成（队友会检查 TaskList，查看可用任务）

工具调用参考

所有 Agent Teams 工具的完整参数规范。可直接复制——参数名称必须完全一致。

TeamCreate

创建一个命名团队。生成队友前调用一次。

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

参数	类型	必填	说明
team_name	string	是	kebab-case 标识符
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

用于团队沟通的三种消息类型。

直接消息（默认——大多数沟通场景均使用此类型）：

{
  "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	5-10 个词的预览，在 UI 中显示

完整团队设置示例

端到端示例：搭建一个 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 — 所有团队任务完成后使用