Agent Teams

2026年9月5日

用 team lead、teammates、共享任务、直接消息和 worktree 隔离协调多个 Claude Code 实例。

Agent Teams 是什么

Agent teams 用来协调多个 Claude Code 实例。一个会话作为 team lead，负责拆分任务、创建 teammates、监控进度并汇总结果。每个 teammate 都是完整的 Claude Code 实例，有自己的上下文窗口。

和 subagents 不同，teammates 可以直接彼此通信，并通过共享任务列表协作。

实验功能

Agent teams 仍是实验功能，默认关闭。只有任务确实需要多 agent 协调时再开启，并预期在恢复会话、任务协调和退出行为上可能存在粗糙边缘。

启用 Agent Teams

设置环境变量，或写入 Claude Code settings：

~/.claude/settings.json

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

然后正常启动 Claude Code，用自然语言要求 teammates。

一个 Team 如何工作

组件	职责
Team lead	主 Claude Code 会话，拆解和协调工作
Teammates	独立 Claude Code 实例，处理分配到的任务
Task list	本地共享任务状态，包含 pending、in progress、completed
Mailbox	agents 之间的直接消息
Display mode	进程内面板，或通过 tmux/iTerm2 分屏

Lead 可以分配任务。Teammates 也可以从共享任务列表中 claim 可做任务。任务 claim 使用锁，避免两个 teammate 同时领取同一个任务。

启动一个 Team

适合用在可以清晰拆分的任务上：

text

I am designing a CLI that tracks TODO comments.
Spawn three teammates:
- one for UX and command design
- one for technical architecture
- one to challenge failure modes

Have them compare findings, then synthesize a final plan.

好的 team 有独立 lane。糟糕的 team 会让多个 agents 模糊地编辑同一批文件。

Subagents vs Agent Teams

维度	Subagents	Agent teams
上下文	独立上下文，结果回到调用方	独立上下文，每个 teammate 都是独立实例
通信	只有 parent-child	Teammates 可直接通信
协调	主 agent 管理所有工作	共享任务列表和自领取
适合	只关心结果的专门任务	需要讨论或互相校验的复杂工作
成本	较低	较高

先用 subagents。只有 workers 需要相互沟通或挑战彼此发现时，再升级到 agent teams。

Dynamic workflows 是另一种选择。当任务需要大量 agents 按 scripted phases 运行，而不是少量 peers 实时协商时，用 dynamic workflows。

适合场景

并行代码审查，每个 teammate 审一个风险类别。
针对复杂 bug 的竞争性假设排查。
新功能设计拆成前端、后端、测试三条线。
架构研究：一个 teammate 提案，一个批判，一个对照代码库验证。

不适合顺序重构、同文件编辑、小 bug fix、依赖关系很紧的任务。

用 Hooks 做质量门

Agent teams 暴露生命周期事件，hooks 可以用来强制质量门：

Hook event	用途
`TaskCreated`	拒绝过大或过模糊的任务
`TaskCompleted`	要求完成前提供测试、摘要或 changed-file list
`TeammateIdle`	在 teammate 停止前发送反馈

这能避免 team coordination 变成不受控的后台过程。

Worktree 策略

Agent teams 和 worktrees 解决并行工作的不同部分：

Team system 负责任务协调。
Worktrees 隔离文件编辑。
Hooks 强制质量门。

多文件实现工作中，给 teammates 清晰 ownership，并优先使用 worktree 隔离。纯研究团队对 worktree 依赖较少。

实用 Prompt 模式

text

Use an agent team for research only.

Teammates:
1. API reviewer: inspect route handlers and validation.
2. DB reviewer: inspect migrations and RLS.
3. Test reviewer: inspect coverage gaps.

Rules:
- Do not edit files.
- Each teammate returns file paths and evidence.
- The lead should synthesize disagreements and recommend next actions.

官方参考

继续实践

Agent Teams 的核心概念已经读完

如果你想把理解变成可复用的能力，可以到 AgentWay 继续练习

进入练习