教程2026-11-17 · 智涌AI

Claude Code Agent Teams 怎么用:组队、分工、用 hook 卡质量

Claude Code Agent Teams 教程头图:左侧大字「Claude Code Agent Teams」与建议 3–5 个队友、2.1.326 可同开 Code Mode、hook 退出码 2 打回任务三张数据卡;右侧终端显示开启 agent teams 的环境变量、让三个队友分别评审 PR 的提示词,以及 TaskCompleted hook 测试失败返回 exit=2、修好后 exit=0 的输出

Claude Code 的 agent teams 让一个会话当队长(lead),再拉起几个独立的 Claude Code 实例当队友:大家共用一张任务清单,队友之间可以直接发消息,你也能绕过队长单独找某个队友说话。功能还是实验性的,默认关着;11 月 17 日的 2.1.326 起,开着 teams 也能用 Code Mode。下面按官方文档把开启、分工、看队友、权限和质量关卡走一遍,最后两个 hook 脚本我在机器上用官方示例 JSON 跑过。

先判断:这活该不该开团队

官方文档开头就劝人先看轻一点的方案。三种并行方式的差别:

子 AgentAgent teams手动多会话(worktree)
上下文独立窗口,结果交回主 Agent独立窗口,各干各的完全独立
沟通主要是把结果交回去队友之间直接发消息,共享任务清单靠你自己转述
谁协调主 Agent 管所有活队长分派 + 队友自己认领你
token较低,结果是摘要高,每个队友都是完整实例看你开几个
适合只要结果的小任务需要讨论、互相挑错的复杂活互不相干的几件事

文档点名的强场景有四类:调研和评审、各管一块的新模块、用几个对立假设查 bug、前端后端测试分层同时改。顺序依赖强、要改同一个文件的活,单会话或子 Agent 更划算。

两个队友改同一个文件会互相覆盖。分工时按文件划地盘,每人只碰自己那几份。

前置条件

第一步:打开开关

在 settings.json(或 shell 环境变量)里设:

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

开了之后有个副作用要知道:Claude 平时委派任务时,有时会自己给子 Agent 起名字;在 teams 开着的会话里,被起了名的子 Agent 会直接变成队友启动,而且不弹确认。也就是说你没提「团队」,团队也可能自己组起来。想回到纯子 Agent,把这个变量改成 "0",保存后下一个被起名的子 Agent 就按子 Agent 跑,不用重开会话。注意项目级、本地级 settings 和管理员下发的 managed settings 优先级都比用户级高,在那里设成 1 会盖过你的 0。

第二步:用提示词组队

直接用自然语言说要几个队友、各管什么。官方的入门例子是三个视角互不依赖的调研:

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.

指定人数和模型也行:Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate. 队友用什么模型,按这个顺序取第一个命中的:提示词里点名的模型 → 子 Agent 定义里的 model → 环境变量 CLAUDE_CODE_SUBAGENT_MODEL → 队长当前模型。旧的 teammateDefaultModel 设置在 2.1.234 已移除,留着也不生效。

队友启动时会加载和普通会话一样的项目上下文(CLAUDE.md、MCP 服务器、Skills),但不继承队长的对话历史。所以分派时把任务细节写进去,比如目录、技术栈、要什么格式的结论:

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. Report any issues with severity ratings."

常用的角色可以先写成子 Agent 定义(.claude/agents/ 下),组队时说「using the security-reviewer agent type」。定义里的 tools 和 model 会生效,正文会追加到队友的系统提示里;skills 字段对队友不生效,队友按项目和用户设置加载 Skill。

规模上,官方建议多数情况从 3–5 个队友起步,每人分 5–6 个任务;15 个独立任务配 3 个队友就够开头。复杂或有风险的改动,先把队长切到 plan 模式再组队,队友会先出方案、批准后才动手。

第三步:看住队友

默认是进程内模式,队友列表在输入框下方的面板里:

想每人一个窗格,在 ~/.claude/settings.json 加 "teammateMode": "auto",然后在 tmux 或 iTerm2 里启动 claude;只想这一次分屏就用 claude --teammate-mode auto。任务清单有待办、进行中、已完成三种状态,可以设依赖,被挡住的任务队友不会自己认领;认领用文件锁,不会两人抢到同一个。活干完了,说一句 Ask the researcher teammate to shut down 让它下线,否则它会一直占 token。

第四步:权限提前放行

队友开工时继承队长的权限模式,包括 --dangerously-skip-permissions 打开的 bypassPermissions,开团队前先想清楚队长在什么模式。进程内队友直接用队长实时的 allow/deny 规则;分屏队友不吃 --allowedTools,要预先放行就写进启动时的 --settings:

claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}'

队友的权限确认框都弹在队长会话里。队友之间发的消息会被标成来自另一个 Claude 会话,不能代你批准权限,被拒的操作也不能转给别的队友绕过去。2.1.326 还加了一条启动告警:--allowedTools、--disallowedTools、--tools 里有写得不完整的规则时会提示,用 teams 前正好借这个查一遍。

第五步:用 hook 卡住质量

teams 有三个专用 hook 事件:TaskCreated、TaskCompleted、TeammateIdle,都不支持 matcher,每次都触发;脚本以退出码 2 结束,就把 stderr 当反馈退回去,任务不关、队友不歇。我写了两段放在 .claude/hooks/:

#!/bin/bash
# task-gate.sh — TaskCompleted:测试不过,任务不许关
INPUT=$(cat)
SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
WHO=$(echo "$INPUT" | jq -r '.teammate_name // "lead"')
LOG=$(mktemp)
if ! python3 -B -m unittest discover -s tests -q >"$LOG" 2>&1; then
  echo "[$WHO] 测试没过,先修好再关任务:$SUBJECT" >&2
  tail -n 3 "$LOG" >&2
  rm -f "$LOG"; exit 2
fi
rm -f "$LOG"; exit 0
#!/bin/bash
# idle-gate.sh — TeammateIdle:reviewer 没交报告,不许停
INPUT=$(cat)
WHO=$(echo "$INPUT" | jq -r '.teammate_name')
case "$WHO" in
  *reviewer*)
    if [ ! -s "review/$WHO.md" ]; then
      echo "把结论写进 review/$WHO.md 再停" >&2
      exit 2
    fi ;;
esac
exit 0

项目的 .claude/settings.json 里这样挂:

{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
  "hooks": {
    "TaskCompleted": [
      { "hooks": [ { "type": "command", "command": ".claude/hooks/task-gate.sh" } ] }
    ],
    "TeammateIdle": [
      { "hooks": [ { "type": "command", "command": ".claude/hooks/idle-gate.sh" } ] }
    ]
  }
}

我在一个带故意写错的 add() 和一条单元测试的小目录里,把 hooks 文档里的示例输入(teammate_name 分别为 implementer、security-reviewer)直接用管道喂给两个脚本(bash 5.2.37、jq 1.7、Python 3.13.5):

--- TaskCompleted,add() 写成 a - b
[implementer] 测试没过,先修好再关任务:Implement add()
Ran 1 test in 0.001s

FAILED (failures=1)
exit=2
--- TaskCompleted,改回 a + b
exit=0
--- TeammateIdle,没有 review/security-reviewer.md
把结论写进 review/security-reviewer.md 再停
exit=2
--- TeammateIdle,报告已写
exit=0

第一版脚本没加 -B,改完代码马上重跑仍报失败:同一秒内改动、文件大小又没变,Python 读到了旧的 .pyc 缓存。加 python3 -B(或删掉 __pycache__)后才正常。几个队友会同时触发 hook,日志我也从固定路径改成了 mktemp。

常见坑

完成标准

子 Agent 的写法和适用面见 Claude Code 子 Agent 教程,hook 的基础配置见 hooks 护栏教程;想和 Code Mode 一起用,先看 Code Mode 上手和 2.1.326 快讯。

最后

第一次用,挑一个不写代码的活:让三个队友分别从安全、性能、测试覆盖三个角度评审同一个 PR,各自把结论写进 review/,你只看队长最后的汇总。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。