Claude-Code-Agent-Teams-实战笔记

Claude Code Agent Teams 实战笔记：什么时候该用，怎么用，哪里容易踩坑

基于我在 2026-03-10 浏览的官方文档整理： Claude Code 官方文档：Agent Teams

先说结论

Agent Teams 不是“多开几个窗口”这么简单，它更像一个小型协作系统：有队长（lead）、队员（teammates）、共享任务列表（task list）和消息机制（mailbox）。

如果你的任务本身适合并行，这个功能能明显提速。

如果任务强依赖串行步骤、多人会改同一个文件，它反而会拖慢你，还更烧 token。

它解决的核心问题是什么

单个 AI 会有一个常见问题：容易早早锁定某条思路。

Agent Teams 的价值在于“并行探索 + 互相挑战”。

官方给的高价值场景，我觉得很准：

• 研究/评审类任务（多人从不同角度审）
• 新模块拆分开发（每人负责独立块）
• 复杂 bug 假设并行验证（互相证伪）
• 跨前后端+测试协同改动

一句话：任务能拆、子任务之间相对独立，就值得开团队。

和 Subagents 的区别（最容易混淆）

很多人会纠结：我到底该用 subagents 还是 agent teams？

可以这样判断：

• Subagents：轻量，结果回主会话，成本低，适合“派出去查完就回来”
• Agent Teams：每个队员是独立 Claude Code 会话，能彼此直接沟通，适合需要讨论和协作的复杂任务

如果你的目标是“多角度碰撞观点”，选 agent teams。

如果只是“找人做一件快活然后汇报”，subagents 更划算。

快速上手（最短路径）

1）先启用实验功能

在 settings.json 或环境变量里加：

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

2）用自然语言让 Claude 组队

比如你可以直接说：

• 让 3 个队员分别负责 UX、架构、反对者视角
• 或明确指定 4 个队员，并指定模型（如 Sonnet）

3）选显示模式

• in-process：都在主终端里，Shift+Down 轮询队员
• split panes：每个队员一个 pane（依赖 tmux 或 iTerm2 + it2 CLI）
• 默认 auto：在 tmux 里用分屏，否则 in-process

如果只是先试用，建议先 in-process，门槛最低。

团队是怎么运作的（理解后会少走弯路）

核心机制有三个：

1. 共享任务列表：任务状态是 pending / in progress / completed
2. 任务可依赖：前置任务不完成，后续任务不能 claim
3. 竞争 claim 通过文件锁避免冲突

另外两个很关键的实现细节：

• 队员上下文独立，不继承 lead 的对话历史
• 但会加载相同项目上下文：CLAUDE.md、MCP、skills

本地落盘路径也给你：

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

质量控制：别只追“并行”，要追“可控并行”

我自己最推荐这三条：

• 对高风险任务开启“先计划后执行”（plan approval）
• 用 hooks 做硬门槛（TeammateIdle、TaskCompleted，返回 code 2 可阻断）
• 明确审批标准（比如“没测试覆盖就不通过计划”）

这能显著降低“多人并行但质量失控”的概率。

成本和团队规模怎么拿捏

这里不要理想化。官方写得很直白：agent teams 的 token 消耗明显高于单会话。

实操建议：

• 先从 3-5 人开始
• 给每人约 5-6 个任务
• 任务过小会被协调成本吃掉，过大又会失控

一句很实在的话：3 个目标清晰的队员，通常比 5 个分工模糊的队员更快。

常见坑（以及怎么救）

高频问题基本就这些：

• 看不到队员：先用 Shift+Down 轮询；再检查任务是否真的值得组队
• 权限弹窗太多：提前在 permission settings 预授权常用操作
• 队员报错后停住：直接给它补指令，或者换一个新队员接手
• lead 过早收工：明确要求“等所有队员完成再继续”
• tmux 残留会话：tmux ls + tmux kill-session -t <name>

现在的限制（必须知道）

Agent Teams 仍是实验特性，主要限制包括：

• in-process 队员不能靠 /resume 或 /rewind 恢复
• 任务状态可能滞后，必要时要手动修正
• 关闭队员可能慢（会先跑完当前调用）
• 一个会话只能带一个团队
• 不支持嵌套团队（队员不能再拉队）
• 队员权限默认继承 lead 的启动权限
• 分屏模式不支持 VS Code 内置终端、Windows Terminal、Ghostty

最后给一个实用判断公式

如果你的任务同时满足这三条，就很适合上 Agent Teams：

• 能拆成多个相对独立子任务
• 子任务之间需要交流或互相挑战
• 你愿意为更快收敛支付更高 token 成本

否则，先用单会话或 subagents，往往更省心。