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

Claude Code 的 agent teams 让一个会话当队长(lead),再拉起几个独立的 Claude Code 实例当队友:大家共用一张任务清单,队友之间可以直接发消息,你也能绕过队长单独找某个队友说话。功能还是实验性的,默认关着;11 月 17 日的 2.1.326 起,开着 teams 也能用 Code Mode。下面按官方文档把开启、分工、看队友、权限和质量关卡走一遍,最后两个 hook 脚本我在机器上用官方示例 JSON 跑过。
先判断:这活该不该开团队
官方文档开头就劝人先看轻一点的方案。三种并行方式的差别:
| 子 Agent | Agent teams | 手动多会话(worktree) | |
|---|---|---|---|
| 上下文 | 独立窗口,结果交回主 Agent | 独立窗口,各干各的 | 完全独立 |
| 沟通 | 主要是把结果交回去 | 队友之间直接发消息,共享任务清单 | 靠你自己转述 |
| 谁协调 | 主 Agent 管所有活 | 队长分派 + 队友自己认领 | 你 |
| token | 较低,结果是摘要 | 高,每个队友都是完整实例 | 看你开几个 |
| 适合 | 只要结果的小任务 | 需要讨论、互相挑错的复杂活 | 互不相干的几件事 |
文档点名的强场景有四类:调研和评审、各管一块的新模块、用几个对立假设查 bug、前端后端测试分层同时改。顺序依赖强、要改同一个文件的活,单会话或子 Agent 更划算。
两个队友改同一个文件会互相覆盖。分工时按文件划地盘,每人只碰自己那几份。
前置条件
- Claude Code 已能正常登录使用。想和 Code Mode 一起开,要 2.1.326 或更新版本;我这台机器上
claude --version显示 2.1.309,升级用claude update。 - 交互式会话。用
-p的非交互模式(包括 Agent SDK 会话)不会拉起队友,Claude 起名的子 Agent 照旧按普通子 Agent 跑。 - 想要分屏:装好 tmux,或者 iTerm2 加
it2CLI 并在设置里打开 Python API。默认的进程内模式任何终端都行。
第一步:打开开关
在 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 模式再组队,队友会先出方案、批准后才动手。
第三步:看住队友
默认是进程内模式,队友列表在输入框下方的面板里:
- 上下方向键选队友,Enter 打开它的记录并直接给它发消息,Esc 打断它当前这一轮。
- 选中后按
x停掉它;Ctrl+T开关任务清单。 - 在队友视图里打的普通文字和 Skill 发给队友,内置命令仍作用于队长:
/compact、/clear、/rewind会先让你确认,/model、/fast在这个视图里不执行。
想每人一个窗格,在 ~/.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。
常见坑
- 以为面板里有人就是组了队。Claude 有时用子 Agent 代替队友,两者出现在同一个面板里。没组成就再说一遍,明确要求「agent team」。
- /resume 之后队友没了。进程内队友不会随
/resume、/rewind恢复,队长可能还在给不存在的队友发消息,让它重新拉起队友即可。 - 任务卡住。队友有时忘了把任务标成完成,依赖它的任务就一直被挡。先看活是不是其实干完了,再手动改状态或让队长催一下。
- 队长自己动手。队长有时不等队友就自己开写,说一句
Wait for your teammates to complete their tasks before proceeding。 - 手写团队配置。
~/.claude/teams/<team>/config.json是运行时状态,会被覆盖;项目里放.claude/teams/teams.json也不会被识别。可复用的角色请写成子 Agent 定义。 - 一个会话只能有一个团队,队友不能再拉自己的队友,队长也不能移交。
完成标准
- 面板里能看到你点名的几个队友,Enter 能进入任意一个的记录并发消息。
Ctrl+T打开的任务清单里,任务从待办走到已完成,没有长时间卡在进行中的。- 故意让测试失败时,队友关任务会被 hook 拦下并收到那句反馈;修好后能正常关闭。
- 收尾时队友都已下线,
tmux ls里没有残留会话。
子 Agent 的写法和适用面见 Claude Code 子 Agent 教程,hook 的基础配置见 hooks 护栏教程;想和 Code Mode 一起用,先看 Code Mode 上手和 2.1.326 快讯。
最后
第一次用,挑一个不写代码的活:让三个队友分别从安全、性能、测试覆盖三个角度评审同一个 PR,各自把结论写进 review/,你只看队长最后的汇总。