agent-teams

Agent 团队

将多个 Claude Code 实例协调成一个团队，共享任务列表、进行 Agent 间消息传递，并使用独立的上下文窗口。它与子 Agent（Task 工具）有本质区别：队友可以直接相互交流，而不只是向调用者汇报。

何时使用 Agent 团队，何时使用子 Agent

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

最佳使用场景：

• 同时从多个角度进行研究和审查
• 多模块功能，由队友分别负责不同文件
• 使用不同假设进行调试（对抗式调查）
• 跨层协调（前端、后端、测试）

避免用于：

• 存在许多依赖项的顺序任务
• 编辑同一个文件（会导致覆盖）
• 简单、目标明确的工作（协调开销得不偿失）
• 常规任务（单个会话更具成本效益）

环境设置

启用 Agent 团队（实验性功能，默认禁用）：

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

或者在 shell 中设置：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

工具架构

Agent 团队使用四种不同的工具（而不是单一的 “TeammateTool”）：

工具	用途
TeamCreate	创建团队配置和任务目录。调用者成为负责人
SendMessage	所有 Agent 间通信（以下 5 种消息类型）
TeamDelete	关闭团队后移除团队资源（清理）
Task（扩展）	当存在 name 和 team_name 参数时，生成队友

SendMessage 类型

类型	参数	说明
message	recipient、content、summary	向一位队友发送直接消息
broadcast	content、summary	向所有队友发送消息（开销较大 — N 次投递）
shutdown_request	recipient、content	请求终止队友（仅负责人可用）
shutdown_response	request_id、approve、content	接受或拒绝关闭请求（仅队友可用）
plan_approval_response	request_id、approve、recipient、content	批准或拒绝计划（仅负责人可用）

重要： 队友看不到纯文本输出。Agent 必须使用 SendMessage 进行所有 Agent 间通信。

使用说明：

• 优先使用 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 服务、技能）
• 负责人的生成提示词
• 不会继承负责人的对话历史

内置队友 Agent 类型：

类型	能力
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 向一位指定队友发送消息。用于发送有针对性的指令、后续跟进或调整工作方式。

广播（type: "broadcast"）： 通过 SendMessage 同时向所有队友发送消息。请谨慎使用——成本会随团队规模增加。适用场景：宣布共同决策、请求状态更新。

自动送达： 消息会自动送达接收者。负责人无需轮询更新。

空闲通知： 队友完成工作并停止后，会自动通知负责人。

消息类型架构： 参见 assets/message-formats.yml

任务协调

共享任务列表用于协调团队工作。所有 Agent 都能看到任务状态，并可领取可用任务。

任务生命周期： pending → in_progress → completed

分配模式：

• 负责人明确分配（“把任务 3 分配给安全审查员”）
• 自行领取：完成任务后，队友会选择下一个未分配且无阻塞的任务

依赖关系：

• 使用 blockedBy 字段（任务 ID 数组）表示
• 自动解除阻塞：阻塞任务完成后，被阻塞的任务即可开始
• 无需轮询即可实现顺序工作流

文件锁定： 领取任务时会使用文件锁定，防止多位队友同时领取时发生竞态条件。

建议的任务规模：

• 每位队友分配 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.

避免文件冲突

两位队友编辑同一文件会导致内容被覆盖。通过分配文件所有权来避免此问题：

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

反模式： 多位队友同时修改共享配置文件、package.json 或迁移文件。

缓解方法： 使用任务依赖关系，按顺序编辑共享文件。

钩子集成

两个用于在 Agent 团队中实施质量门禁的钩子事件：

TeammateIdle

当队友完成其轮次、即将进入空闲状态时触发。

• Exit 0 → 允许进入空闲状态
• Exit 2 → 继续工作（stderr 会作为反馈传回给队友）
• 不支持匹配器（每次都会触发）
• 输入包括：teammate_name、team_name

TaskCompleted

当任务即将被标记为已完成时触发（通过 TaskUpdate，或队友完成进行中的任务时）。

• Exit 0 → 允许完成
• Exit 2 → 阻止完成（stderr 会作为反馈传回）
• 不支持匹配器（每次都会触发）
• 输入包括：task_id、task_subject、task_description、teammate_name、team_name

**TeammateIdle：**仅支持命令钩子（不支持提示词/Agent 钩子）。**TaskCompleted：**支持命令、提示词和 Agent 处理程序类型。

配置示例请参见 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

重要提示：

• 关闭可能较慢——队友会先完成当前请求，再终止
• 清理时始终使用 lead（不要使用队友）
• 对于孤立的 tmux 会话：tmux ls && tmux kill-session -t <name>

权限

• 队友启动时使用 lead 的权限设置
• 如果 lead 使用 --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 不会恢复队友	恢复后告知 lead 生成新的队友
任务状态可能滞后	队友有时不会将任务标记为已完成	手动更新，或告知 lead 提醒队友
关闭可能较慢	队友会先完成当前请求，再停止	耐心等待或生成替代队友
每个会话只能有一个团队	无法通过一个 lead 管理多个团队	启动新团队前清理当前团队
不支持嵌套团队	队友无法生成自己的团队	只有 lead 可以管理团队结构
lead 固定不变	无法提拔队友或转移领导权	启动前规划团队结构
权限在生成时设定	所有队友都会继承 lead 的权限模式	生成后更改各队友的模式
分屏窗格需要 tmux/iTerm2	VS Code 终端、Windows Terminal、Ghostty 不支持	使用进程内模式作为备用方案
心跳超时为 5 分钟	不活跃的队友会被自动标记为不活跃	通过分配任务让队友保持活跃
广播随人数线性扩展	N 个队友会产生 N 条消息	优先使用定向 message，而不是 broadcast
委派模式下的生成 Bug	按 Shift+Tab 后生成的队友会失去文件工具	进入委派模式前生成所有队友

错误处理

错误	原因	修复方法
"Cannot cleanup with active members"	队友仍在运行	先对所有队友执行 requestShutdown
"Already leading a team"	团队已存在	对现有团队执行 cleanup，或使用其他名称
"Agent not found"	队友名称/ID 错误	检查 config.json 中正确的 Agent ID
"Team does not exist"	尚未创建团队	先运行 spawnTeam
队友未显示	原因不一	按 Shift+Down 切换；检查任务复杂度；确认已安装 tmux
权限提示过多	队友权限会传递给 lead	在设置中预先批准常见操作
lead 在工作完成前关闭	lead 认为团队已完成工作	告知 lead 等待队友完成

编排模式

有关 4 种详细模式，请参阅 references/orchestration-patterns.md：

1. 并行审查 — 多位专家从不同视角同时审查
2. 竞争性假设 — 对抗式调查有助于避免锚定偏差
3. 多模块功能 — 通过文件所有权和任务依赖关系协调实施
4. 研究流水线 — 研究阶段为经计划审批的实施提供依据