Agent Teams：组建你的 AI 开发小队

Gundy
0 阅读19分钟
  1. 软件开发行业的 AI 范式演进：从辅助工具到工程智能体
  2. Claude Code 全景入门：装好、看懂、跑起来
  3. 上下文注入：用 @ 和 ! 精准喂给 Claude 它需要的信息
  4. 记忆系统：用 CLAUDE.md 告别每次对话都要"重新认识你"
  5. 斜杠命令：把你的重复操作变成一个单词
  6. Hooks 机制：让 AI 的每一步都在你的规则里
  7. MCP：给 Claude Code 接上"外设"
  8. Skills：让 Claude 按需加载你的领域知识
  9. Sub-agents：给 Claude 分身，让专家各司其职
  10. Agent Teams：组建你的 AI 开发小队
  11. 安全与回退：给 AI 戴上"安全带"
  12. SDK 与 Headless：把 Claude 变成你的自动化引擎
  13. 上下文工程：从记忆文件到分层知识架构
  14. 模型选择与成本控制：把每一分钱花在刀刃上

qrcode_for_gh_6219b0488be5_258.jpg

08 | Agent Teams：组建你的 AI 开发小队

上一篇讲 Sub-agents 的时候，我说它的核心是"隔离"——把高噪声的中间过程关在独立上下文里，只把结论带回来。用了一段时间之后，确实解决了主对话被塞满的问题。

但有一个场景始终不太顺畅。

我们 SCRM 系统上线前有一次紧急排查。运营反馈说部分客户的跟进记录"串号"了——A 客户的跟进记录出现在 B 客户名下。同时 API 响应时间也变慢了。两个症状看起来没关联，但我隐约觉得可能有共同的根因。

我让 Claude 用 Sub-agent 并行调查：一个查数据串号的逻辑，一个查性能问题。两个 Sub-agent 各自交了报告：数据那边说"缓存 key 没有加 customer_id 前缀"，性能那边说"数据库连接池太小，高并发时排队"。

问题是——连接池耗尽导致部分请求 fallback 到缓存，而缓存 key 没做隔离，这才是数据串号的真正触发条件。两个 bug 是级联关系，单独看都对，合在一起才是完整的故事。

但 Sub-agent 之间不能互相对话。性能 Sub-agent 不知道数据 Sub-agent 发现了什么，反过来也一样。它们各自向主对话汇报，拼接结论的活只能由我来做。任务简单时这没问题，但当各方发现之间有复杂的因果关系时，光靠"汇总报告"很难把级联效应串起来。

Agent Teams 解决的就是这个问题。

从"派出去汇报"到"组队讨论"

先回顾一下 Sub-agents 的工作模式：主对话是"老板"，Sub-agent 是"员工"。老板派员工去做事，员工在自己的办公室里干完活，把结论带回来。员工之间不交流——它们不知道彼此的存在。

这种模式在大多数场景下够用：搜索代码、跑测试、审计合规——每个任务独立，结论汇总就行。

但有些任务不是这样的。比如排查那个"数据串号 + API 变慢"的问题——两个调查方向的发现会互相影响。如果"数据调查员"能看到"性能调查员"说的"连接池耗尽时请求 fallback 到缓存"，它会立刻意识到"缓存 key 没隔离"这个发现的严重性被低估了——不是偶尔走缓存，而是高并发时必然走缓存。

Agent Teams 的核心区别就在这里：

Sub-agentsAgent Teams
上下文独立窗口，结论返回主对话独立窗口，完全自治
通信只向主对话汇报队员之间可以直接通信
协调主对话管理所有工作共享任务列表，自主协调
适合结论汇总型任务需要讨论、挑战、协作的复杂任务
Token 成本较低较高（每个队员是独立的 Claude 实例）

一句话总结：Sub-agents 是"派出去—带回来"，Agent Teams 是"组队讨论"。

Agent Teams 的架构

一个 Agent Team 由四个组件构成：

Team Lead（队长）：就是你当前的 Claude Code 会话。它负责拆解任务、分配工作、协调进度、合成结果。它是唯一能创建和解散团队的角色。

Teammates（队员）：完全独立的 Claude Code 实例，每个有自己的上下文窗口。它们启动时会加载项目的 CLAUDE.md、MCP servers、Skills——和正常启动一个 Claude Code 会话一样。但不继承 Lead 的对话历史。

Task List（共享任务列表）：所有队员可见的任务板。Lead 创建任务，队员认领和完成。任务有依赖关系——被阻塞的任务在依赖完成前不能被认领。

Mailbox（消息系统）：队员之间的通信通道。支持两种消息：DM（发给指定队员）和 Broadcast（发给所有人，慎用——成本随队员数线性增长）。

团队数据存储在本地：

~/.claude/teams/{team-name}/config.json    ← 团队配置（成员列表）
~/.claude/tasks/{team-name}/               ← 共享任务列表

开启 Agent Teams

Agent Teams 目前是实验性功能，默认关闭。需要手动开启。

在 settings.json（用户级 ~/.claude/settings.json 或项目级 .claude/settings.json）中添加：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

或者在 shell 里设置环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

开启之后，你就可以用自然语言告诉 Claude 创建团队了。Claude 不会未经你同意自动创建——它会先提议，你确认后才行动。

用自然语言组建团队

拿我们 SCRM 系统的场景来说。假设运营报了两个问题：客户跟进记录偶尔串号、API 响应变慢。我不确定这两个问题是否关联，想让多个调查员并行排查、互相验证。

直接告诉 Claude：

客户跟进记录出现串号，同时 API 响应变慢。两个症状可能有关联。
创建一个 agent team 来调查：

1. "缓存调查员"：假设根因在缓存层，重点查 middleware/cache 和缓存 key 的隔离逻辑
2. "数据库调查员"：假设根因在数据库连接和查询层，重点查连接池配置和慢查询
3. "数据流调查员"：不预设假设，从整体数据流角度分析，关注请求在各层之间的流转

每个调查员用 Read/Grep/Glob 审查代码。
找到可疑问题后要发消息告诉其他调查员。
如果别人的发现和自己的有关联，主动指出。
特别注意：两个症状可能不是独立的，要寻找因果关系。

最终综合所有发现，输出一份调查报告。

Claude 会化身 Team Lead，创建团队、生成三个 Teammates、分配初始任务。每个 Teammate 在自己的上下文里独立调查，通过消息系统交换发现。

这就是 Agent Teams 和 Sub-agents 的体感区别：你不需要自己当"中间人"拼接各方报告——调查员之间自己对话、挑战、补充。

显示模式

Agent Teams 支持两种显示模式：

In-process（进程内）：所有队员在你的主终端里运行。用 Shift+Down 在队员之间切换，直接输入就是给当前队员发消息。任何终端都能用，不需要额外配置。

Split panes（分屏）：每个队员一个独立面板，同时看到所有人的工作状态。需要 tmux 或 iTerm2 支持。

默认是 auto——如果你在 tmux 里就用分屏，否则用进程内模式。想固定用某种模式，在 settings.json 里设置：

{
  "teammateMode": "in-process"
}

或者启动时指定：

claude --teammate-mode in-process

如果条件允许，推荐用分屏模式——同时看到所有队员的"思考过程"，对于理解团队协作的效果非常直观。

四种协作模式

Agent Teams 的威力在于不同的协作模式。从实际工程场景出发，有四种典型用法：

竞争假设

适合：根因不明确、需要多方向同时验证的排查场景。

用户反馈消息发送后应用直接退出，没有保持连接。
生成 5 个 agent teammates 调查不同假设。
让它们互相对话，试图推翻对方的理论，像科学辩论。
最终共识更新到 findings 文档。

核心机制是辩论。单个调查员容易"锚定"——找到一个合理解释就停下来。多个独立调查员互相反驳，存活下来的理论更可能是真正的根因。这比顺序调查靠谱得多：顺序调查一旦第一个理论被探索，后续分析会不自觉地偏向它。

分层评审

适合：代码审查、PR Review 等需要多维度评估的场景。

创建一个 agent team 审查 PR #87。三个 reviewer：
- 一个专注安全隐患
- 一个检查性能影响
- 一个验证测试覆盖
各自审查后汇报发现。

单个 reviewer 容易聚焦于某一类问题。拆成三个维度并行审查，每个维度都得到充分关注。而且不同维度可能发现关联问题——安全 reviewer 发现的输入验证问题可能恰好是性能瓶颈的来源。

模块化开发

适合：新功能开发，涉及多个独立模块（前端、后端、测试）的场景。

Lead 把工作拆成模块，每个 Teammate 拥有一个模块。通过共享任务列表协调工作，任务可以声明依赖——"测试任务"依赖"后端 API 任务"，后端完成后测试自动解锁。

关键约束：每个 Teammate 负责不同的文件，避免两个人同时编辑同一个文件导致覆盖。

规划-审批

适合：复杂或高风险任务，需要在实施前确认方案。

生成一个 architect teammate 重构认证模块。
要求在修改任何代码前先提交计划等待审批。
只批准包含测试计划的方案。
拒绝修改数据库 schema 的方案。

Teammate 在只读的 plan mode 下工作，完成规划后提交给 Lead 审批。Lead 根据你给的标准自主决定批准或拒绝。被拒绝的 Teammate 留在 plan mode 里修改方案，重新提交。审批通过后才能开始实施。

团队的生命周期

创建

两种方式：你主动要求（"创建一个 agent team..."），或者 Claude 判断任务适合并行后提议创建。无论哪种，你确认后才执行。

工作中

Lead 分配任务，Teammates 认领和执行。你可以随时介入：

  • 给特定队员发消息：Shift+Down 切换到目标队员，直接输入
  • 查看任务列表：Ctrl+T 切换任务面板
  • 让 Lead 等待：如果 Lead 自己"抢活"了，告诉它"等队员完成再继续"

关闭

工作完成后，让 Lead 关闭团队：

关闭团队

Lead 向每个 Teammate 发送关闭请求。Teammate 可以批准（退出）或拒绝（说明原因，比如"还有一个任务没完成"）。所有 Teammate 关闭后，Lead 清理团队资源。

始终让 Lead 来做清理——Teammate 的团队上下文可能不完整，由它清理可能留下残余。

权限和上下文

权限：Teammates 启动时继承 Lead 的权限设置。如果 Lead 用了 --dangerously-skip-permissions，所有 Teammates 也是如此。启动后可以单独调整某个 Teammate 的权限，但不能在创建时设定。

上下文：每个 Teammate 启动时加载项目的 CLAUDE.md、MCP servers、Skills——和你自己开一个新的 Claude Code 会话一样。但不继承 Lead 的对话历史。所以创建团队时，给每个 Teammate 的 prompt 要包含足够的上下文信息：

生成一个安全审计 teammate，prompt 如下：
"审查 internal/customer/ 目录的数据处理逻辑。
重点关注 PII 存储、日志安全和企微 access_token 管理。
项目使用 Go + pgx，客户数据涉及手机号和微信号。
发现问题标注严重等级。"

不要假设 Teammate 知道你和 Lead 之前聊过什么——它不知道。

质量保障：Hooks 集成

Agent Teams 支持两个专用 Hook，用于在团队工作中自动执行质量检查：

TeammateIdle：当 Teammate 即将进入空闲状态时触发。Hook 以退出码 2 退出时，会把 stderr 内容作为反馈发送给 Teammate，让它继续工作。比如检查 Teammate 是否真的完成了所有分配的任务：

{
  "hooks": {
    "TeammateIdle": [
      {
        "type": "command",
        "command": "./scripts/check-teammate-tasks.sh"
      }
    ]
  }
}

TaskCompleted：当任务被标记为完成时触发。退出码 2 阻止完成并发送反馈。可以用来强制执行"提交前必须通过测试"之类的质量门禁。

Sub-agents 还是 Agent Teams？

一个简单的决策树：

任务需要多个 workers 吗？
├── 否 → 主对话或单个 Sub-agent
└── 是 → Workers 需要互相通信吗？
    ├── 否 → Sub-agents
    │   • 更低 token 成本
    │   • 更简单的协调
    │   • 适合：并行探索、流水线编排、结论汇总
    │
    └── 是 → Agent Teams
        • 支持讨论和挑战
        • 共享任务列表
        • 适合：竞争假设、协作开发、多角度审查

核心判断标准：workers 是否需要互相通信？ 只需汇报结果就选 Sub-agents，需要互相讨论、挑战、协调就选 Agent Teams。

实际工作中大多数任务用 Sub-agents 就够了。Agent Teams 的价值在那些"各方发现之间存在复杂因果关系"的场景——单纯汇总报告不够，需要调查员之间直接对质才能把故事拼完整。

成本意识

Agent Teams 的 token 消耗远高于单会话和 Sub-agents。每个 Teammate 是独立的 Claude 实例，有独立的上下文窗口。5 个队员的团队，token 消耗速度大约是单会话的 5 倍。

所以要想清楚：

值得用的场景：

  • 并行探索能带来真正的价值（竞争假设、多角度审查）
  • 讨论和挑战能提高结果质量（级联故障排查）
  • 任务复杂度值得额外成本（跨层协调开发）

不值得用的场景：

  • 常规任务，单会话就够
  • 任务之间没有协作需求
  • 预算有限

推荐从 3-5 个 Teammates 起步。官方建议每个 Teammate 分配 5-6 个任务，保持忙碌的同时也方便 Lead 在某人卡住时重新分配。

几条实战建议

从研究和审查开始。 如果你是第一次用 Agent Teams，从不写代码的任务开始——审查 PR、调研技术方案、调查 bug。这些任务边界清晰，能展示并行探索的价值，又避免了并行写代码时的文件冲突问题。

避免文件冲突。 两个 Teammates 同时编辑同一个文件会导致覆盖。拆分工作时确保每个人拥有不同的文件集。

不要让团队无人看管太久。 定期检查进度，纠正偏离方向的 Teammate。让团队长时间无人监督会增加返工风险。

让 Lead 等队员。 Lead 有时候会自己"抢活"，在 Teammates 完成前就开始下一步。遇到这种情况直接说"等你的队员完成任务后再继续"。

给足上下文。 Teammates 不继承 Lead 的对话历史。创建时把任务相关的信息——文件路径、技术栈、关注点——都写进 spawn prompt 里。

当前局限

作为实验性功能，Agent Teams 有一些已知限制：

  • 不支持会话恢复：/resume 和 /rewind 不会恢复 in-process 模式的 Teammates。恢复后 Lead 可能尝试给已不存在的 Teammates 发消息——告诉它重新创建就行
  • 任务状态可能滞后：Teammates 有时忘记标记任务完成，导致依赖任务被阻塞。发现任务卡住时手动检查，或让 Lead 催一下
  • 关闭可能较慢：Teammates 会完成当前正在执行的操作后才关闭
  • 每个会话只能管一个团队：清理完当前团队才能创建新的
  • 不支持嵌套：Teammates 不能自己再创建团队或 Teammates。只有 Lead 能管理团队
  • 分屏模式需要 tmux 或 iTerm2：VS Code 终端、Windows Terminal 等不支持分屏

回顾整个系列到这里：CLAUDE.md 管记忆，斜杠命令管流程复用，Hooks 管硬约束，MCP 管能力扩展，Skills 管按需知识加载，Sub-agents 管上下文隔离和角色分工，Agent Teams 管多实例协作。

从简单到复杂，从配置到架构，每一层解决的问题不同。不是要你全部用上——按实际痛点选。大多数日常开发，主对话 + CLAUDE.md + 几个 Skills 就够了。Sub-agents 在上下文被塞满时引入。Agent Teams 留给那些真正需要"团队讨论"才能解决的复杂问题。

avatar
文章
阅读
粉丝