Agent Teams 多代理

Agent Teams 多代理

子代理（subagent）是「主代理当项目经理，把活外包给独立上下文的工人」——工人干完只把摘要交回来。这种模式适合「探索—规划—执行—审查」的链条。但有些活需要真正的团队作战：多个 Claude 实例同时存在，互相通信、共享任务列表、各自干自己的活、必要时彼此挑战。这就是 Agent Teams。

子代理 vs Agent Teams

两者都能并行，关键差别在于工人之间是否能对话：

	子代理（Subagents）	Agent Teams
上下文	自有上下文，结果返回给主代理	自有上下文，完全独立
通信	只向主代理报告	队友之间直接互发消息
协调	主代理管理一切	共享任务列表 + 自协调
适合	只关心结果的小活	需要讨论与协作的复杂活
Token 成本	较低（摘要返回）	较高（每个队友都是独立 Claude 实例）

子代理像外包：你下指令，他交货，互不通信。Agent Teams 像团队：共享任务板、互相发邮件、必要时直接讨论。

开启 Agent Teams

Agent Teams 默认关闭（实验性）。开启方法——把 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 设到 settings.json 或环境：

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

不开启时不会创建团队、不写 team 目录、Claude 也不会 spawn 队友。

Agent Teams 有已知限制：会话恢复、任务协调、关闭行为可能不完美。详见官方 limitations 章节。

用自然语言启动一个团队

开启后，直接用自然语言描述任务和你要的队友。Claude 会根据你的 prompt 自动 spawn 队友：

I'm designing a CLI tool that helps developers track TODO comments across their codebase.
Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

三个角色独立又互补——他们可以各自调研，互相挑战对方的发现，最后主代理（team lead）综合产出。

也可以指定数量和模型：

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate.

队友默认不继承 lead 的 /model 选择。要让队友跟随 lead 模型，去 /config 把 Default teammate model 设为 Default (leader’s model)。队友会继承 lead 的 effort level。

–teammate-mode：选显示方式

--teammate-mode 决定队友怎么显示：

模式	行为
auto（默认）	已在 tmux 里或终端是 iTerm2 时用 split panes，否则 in-process
in-process	全部队友在主终端里，用 agent 面板上下选
tmux	强制 split-pane，自动检测 tmux 或 iTerm2

claude --teammate-mode in-process
claude --teammate-mode tmux

也可以写到 ~/.claude/settings.json 的 teammateMode 字段持久化。Split-pane 模式需要 tmux 或 iTerm2（带 it2 CLI）。

团队架构

一个 agent team 由几部分组成：

组件	角色
Team lead	主 Claude Code 会话，spawn 队友并协调
Teammates	独立 Claude Code 实例，各自领任务
Task list	共享任务板，队友认领并完成
Mailbox	agent 之间的消息系统

团队和任务存在本地，名字是 session- 加 session ID 前 8 位：

• 团队配置：~/.claude/teams/{team-name}/config.json
• 任务列表：~/.claude/tasks/{team-name}/

会话结束时 team 配置目录被清掉；任务列表持久化在本地，恢复会话时还能用——和 cleanupPeriodDays 同样的过期策略。

直接和队友对话

每个队友都是完整的独立 Claude Code 会话。你可以直接给它发指令、追问、改方向：

• in-process 模式：在 agent 面板用 ↑/↓ 选队友，Enter 进它的 transcript 直接发消息；x 停止它；Ctrl+T 切任务列表
• split-pane 模式：点进某个 pane 直接和那个会话交互

要求队友先出方案

复杂或风险高的任务，可以要求队友先做规划，lead 审批后再实现：

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

队友在只读 plan 模式下工作，做完规划给 lead 发审批请求。lead 自主决策是否批准；要影响它的判断，在 prompt 里给标准，比如「only approve plans that include test coverage」。

用 hooks 设质量门

用 hooks 在关键节点加硬规则：

• TeammateIdle：队友即将空闲时触发——退出码 2 可发反馈让它继续干
• TaskCreated：任务创建时触发——退出码 2 阻止创建并发反馈
• TaskCompleted：任务标记完成时触发——退出码 2 阻止完成并发反馈

详见 Hooks 深入。

适合的场景

Agent Teams 在并行探索能带来真价值的任务上最有力：

• 研究与审查：多个队友从不同角度调研，互相挑战发现
• 新模块或功能：队友各占一块，互不踩
• 带竞争假设的调试：队友并行测试不同理论，更快收敛
• 跨层协调：前端、后端、测试三层各一个队友负责

不适合：序列任务、同文件编辑、依赖密集的活——单会话或子代理更高效。

Dynamic Workflows：上百个 subagent fan out

2026 年 6 月加入的 Dynamic Workflows 把多代理协作推到了新高度：让 Claude 写一个 JavaScript 脚本来编排大量 subagent，runtime 在后台跑这个脚本，你的会话保持响应。

Dynamic Workflows 需要 Claude Code v2.1.154+，所有付费 plan、Anthropic API、Amazon Bedrock、Google Vertex AI、Microsoft Foundry 都支持。Pro 用户在 /config 的 Dynamic workflows 行开启。

Workflow 把「计划」从 Claude 的 context 挪到了代码里——loop、branch、中间结果都在脚本变量里，Claude 的 context 只持有最终答案。这意味着可以 fan out 几十甚至上百个 subagent，而主会话不会被中间过程撑爆。

维度	Subagents	Agent Teams	Workflows
谁决定下一步	Claude 每轮决定	Lead agent 每轮决定	脚本决定
中间结果在哪	Claude 的 context	共享任务列表	脚本变量
规模	每轮几个	几个长期 peer	几十到上百个
可重复	worker 定义可复用	团队定义可复用	整个编排可复用

适合：repo 级大规模活——80 个模型 × prompt 组合的基准测试、大迁移、全量审计、跨多角度交叉验证的研究问题。

# 跑内置 deep-research workflow
/deep-research What changed in the Node.js permission model between v20 and v22?

要自己写 workflow，在 prompt 里说「让 Claude 写个 workflow」或包含关键字 ultracode，Claude 会规划一个；用 /effort ultracode 则对每个实质任务都尝试规划 workflow。跑通后用 s 保存成命令，下次直接 /你的命令 重跑。

agent-teams 与 time-orchestrator

社区里有一些 best-practice 仓库（如 agent-teams 目录）演示了如何把 team 模式落地到具体场景，配合 time-orchestrator 这类 slash command 做时间维度的编排——把「派 N 个队友干 A、B、C」自动化为可重跑的命令。这类模板适合做模型-提示组合基准、批量改造、全量审计这类需要 fan out 的活。

最佳实践

1. 给足上下文：队友是新会话，没有 lead 的对话历史——把背景写进 prompt
2. 合适规模：队友是独立 Claude 实例，token 成本翻倍——别为了好看开 10 个
3. 任务别太小：每次 spawn 队友有协调开销，太小不如直接做
4. 等队友跑完：lead 提前退出会拖垮整个团队
5. 从研究/审查起步：先在只读场景试，再放到改代码的活
6. 避免文件冲突：让队友改不同文件，或配 worktree 隔离

一句话总结

Agent Teams 是 Claude Code 的「团队作战」模式：lead spawn 多个队友，共享任务板、互发消息、必要时彼此挑战。配上 2026 年 6 月的 Dynamic Workflows，可以 fan out 上百个 subagent 处理 repo 级大规模任务。

下一篇看 Claude Agent SDK，把这种编排能力写成你自己的程序。🧩