Claude Code + Agent Teams，并行任务的最佳实践

大家好，我是鲁工。

前两天翻Claude Code文档，角落里多了一页叫Agent Teams。版本要求是v2.1.32以上，我本地2.1.118，顺手就开了env跑起来。

玩了几天下来发现，这个东西能挖的东西挺多。但官方文档信息密度也不小，各种章节散开看容易抓不到主线。

这篇按官方文档的逻辑顺序串一下：先讲清楚和subagents的区别、什么场景该用、怎么启动、怎么控制、怎么算用得对，再用三个我自己跑过的实测案例落到具体场景。看完这篇基本能从零上手。

Agent Teams到底新在哪里

先快速补个背景。

Claude Code里做多任务并行，之前主要靠Subagents（子智能体）。这块我之前写过一篇《用Subagents打造Claude Code专业开发团队》，感兴趣的朋友可以回去看。

Subagents能有独立的context window、配专用的系统提示、选不同的工具和模型。但它有个天花板：只能向主代理汇报结果，彼此之间没有直接对话的通道。

Agent Teams把这个限制打掉了。

三个维度看差别：

维度	Subagents	Agent Teams
通信	只向主代理汇报	队友之间直接收发消息
协调	主代理统一管理	共享任务列表+自协调
Context	自己的窗口，结果回主会话	自己的窗口，完全独立
Token成本	较低（结果汇总）	较高（每个队友是独立Claude实例）
适合	结果导向的专注任务	需要讨论和质疑的复杂工作

简单来说，Subagents是实习生各自给老板交作业，Agent Teams是小组同事坐一起能互相讨论。

何时该用Agent Teams

不是所有任务都适合开团。这事儿token成本是真的高，一个3人团队的token消耗大概是单会话的3到4倍，盲目滥用会很疼。

官方文档列了几个最强用例：

研究和审查类任务。多个队友可以同时调查问题的不同方面，然后互相分享和质疑彼此的发现。比如审一个PR，三个队友分别负责安全、性能、测试覆盖三个角度。

新模块或功能开发。每个队友拥有一个独立的部分，不会相互干扰。前提是任务可拆，文件不冲突。

带竞争假设的Bug调试。多个队友各拿一个理论并行测试，能更快收敛到根因。这个对抗"找到一个看似合理的解释就停"的锚定偏见特别有用。

跨层协调。前端、后端、测试改动同时进行，每个队友负责一层。

反过来不适合的场景也很明确：

顺序依赖强的任务（B必须等A完成）、同一个文件多人编辑（容易覆盖）、依赖关系特别多的工作。这几种场景下要么用单会话顺序处理，要么用subagents就行，开团反而是负担。

开启Agent Teams

两个前置条件。

一是Claude Code v2.1.32以上（claude --version 查一下）。

二是在 ~/.claude/settings.json 里加一个环境变量：

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

有个坑要提前说一声：env值必须写字符串 "1"，不要写 "true" 或布尔 true。多数程序两种都当启用处理，但Anthropic这个feature gate按文档只认 "1"。改完settings.json要完全退出Claude Code再重开才生效，配置是启动时加载的。

我本地实测过的环境：

$ claude --version
2.1.118 (Claude Code)

$ tmux -V
tmux 3.6a

tmux不是必需的，跟显示模式有关，下面控制操控章节细说。

如何启动团队

启动方式很简单：自然语言告诉Claude你想要什么团队、做什么任务。Claude自己负责创建team lead、生成teammates、协调工作。

官方文档里给的标准例子：

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

这条prompt官方原话是 "This example works well"，三个角色独立、不需要互相等待，开团效果最好。

触发关键词很关键。prompt里必须显式出现 agent team / teammate / team lead / shared task list 这类词，Claude才会走Agent Teams分支。中文口语里说的"开两个agent并行"、"派两个子代理"这种写法会被识别成subagents，直接调Task tool，根本不会创建team。我自己第一次就在这上面卡了挺久，输出一直是 Running N agents... 的subagents形态，找不到team界面。后来发现prompt里关键词不够明确才解决。写中文prompt时这几个英文关键词混着写最稳。

指定队友数和模型。Claude会根据任务自己决定开几个队友，但你也可以直接指定：

Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate.

也可以让不同队友用不同模型，比如 lead 用 Opus、teammate 用 Sonnet 控制成本。

Claude主动提议团队。如果你给的任务确实受益于并行，Claude会主动建议开团，但不会未经你同意就创建。最终决定权在你手里。

判断team是否真的被创建有个硬标准：执行后看 ~/.claude/teams/ 目录下有没有新生成的team目录（带 config.json）。有目录才是真的开团了；没有就是走的subagents。

如何控制和操控Teammates

团队跑起来之后，你不是只能等结果，整个过程都可以介入。

显示模式：in-process和split panes

两种显示模式：

In-process：所有队友都跑在你主终端里，用 Shift+Down 循环切换。任何终端都能用，不用额外装东西。

Split panes：每个队友一个独立窗格，输出全程可见，点击哪个窗格就直接进到对应队友的会话。需要 tmux 或 iTerm2 支持。

启用方式三种，从大到小：

全局config，在 ~/.claude.json 里设：

{
  "teammateMode": "tmux"
}

单次启动flag：

claude --teammate-mode tmux

部分版本 claude --help 里看不到这个flag（我本地 2.1.118 就没列出），不放心的话优先用上面全局config的方式。

默认 auto 模式：你已经在tmux session里打开Claude Code，Claude会自动切split panes，否则回到in-process。

split panes的两种入口：tmux（macOS下最稳定）；iTerm2（需要装 it2 CLI，并在 Settings → General → Magic 开 Enable Python API）。

直接和队友对话

每个队友都是完整独立的Claude Code会话，可以直接给它们发消息：

In-process模式：Shift+Down 切到目标队友，输入消息直接发；Enter 进入队友会话查看详情，Escape 中断当前轮次；Ctrl+T 调出共享任务列表。

Split-pane模式：直接点击窗格就能进对应队友的会话，每个队友有完整终端视图。

任务分配和认领

共享任务列表协调整个团队的工作。任务有三种状态：pending、in progress、completed，还可以设置依赖关系（一个任务blocked by另一个时，依赖任务不解除就不能认领）。

两种分配方式：lead显式指派（"把这个任务给researcher队友"），或者队友完成自己的任务后自动认领下一个未分配的。

计划批准模式

复杂或风险高的任务可以要求队友先做planning，lead审过才动手：

Spawn an architect teammate to add structured logging middleware. Require plan approval before any changes. Reject any plan that does not include rollback strategy and test coverage.

关键：在prompt里给lead写清楚批准准则（"必须包含测试覆盖"、"必须有回滚方案"），不然lead会按自己的判断批。被拒绝的队友会留在plan模式，按反馈修订重新提交。

关闭和清理

关闭单个队友：

Ask the researcher teammate to shut down

队友收到关闭请求可以批准或拒绝。

整个团队跑完，跟lead说一句：

Clean up the team

这会删除共享团队资源。如果还有队友在跑，清理会失败，先关闭它们再清。这一步必须由lead执行，队友自己跑clean会出问题。

用hooks强制质量门

Agent Teams配套了三个新的hook事件：TeammateIdle（队友空闲时）、TaskCreated（任务创建时）、TaskCompleted（任务完成时）。在hook里以exit 2退出可以阻断对应行为，stderr内容会作为反馈传给teammate。

适合把团队规范硬编码进去，比如"任务标记完成前必须跑过测试"、"不允许创建修改数据库schema的任务"。比prompt里反复叮嘱可靠得多，prompt是软约束模型可能忘，hook是硬约束直接拦住。

三个实测案例

下面三个案例我都跑过，分别覆盖最常用的三种场景。

案例一：一句话调研开团

最常规的玩法，给一个调研任务+大致角色分工，剩下交给Claude。

Create an agent team to research how Skills, Subagents and Plugins differ in Claude Code. Spawn three teammates: one reads the official docs, one scans community discussions on X and Reddit, one compares actual repos that use each. Have them compile a shared findings doc.

跑下来Claude会自动创建team lead加3个teammates，各跑各的方向，最后lead综合输出。

实测分工：本地环境我已经确认好（版本/env/tmux）。这条prompt直接复制就能跑，观察team lead分工逻辑、三人综合报告这部分留给你亲自跑一遍。

案例二：并行代码审查

Agent Teams最经典的实战场景。三个reviewer各自聚焦一个维度，同时审同一段代码。

实测demo代码，把下面这段保存成 app.py：

import hashlib
import json
from flask import Flask, request

app = Flask(__name__)
users = {}

@app.route('/register', methods=['POST'])
def register():
    data = request.get_json()
    username = data['username']
    password = data['password']
    pwd_hash = hashlib.md5(password.encode()).hexdigest()
    users[username] = {
        'password': pwd_hash,
        'role': data.get('role', 'user')
    }
    return json.dumps(users)

if __name__ == '__main__':
    app.run()

代码里故意埋了几个典型问题：MD5弱哈希、role 字段从请求体裸取可被提权、无任何异常处理、注册接口返回全量用户信息（隐私+性能）、零测试覆盖。三个视角各找各的，正合适。

审查prompt：

Create an agent team to review app.py. Spawn three reviewers:

One focused on security (OWASP Top 10, auth, credential handling)

One on performance and data exposure

One on test coverage and error handling

Each writes findings to the shared task list. The lead synthesizes a final report grouped by severity (CRITICAL / HIGH / MEDIUM / LOW).

实测分工：demo代码已经嵌在文章里，复制保存即可。跑完三个reviewer对比他们各自找出的问题+lead综合后的严重度分档，留给你。重点看lead是不是抓住了最关键的两条（MD5弱哈希 + role提权）。

案例三：复用subagent定义当队友

进阶玩法。你在 ~/.claude/agents/ 目录下定义过的subagent，可以直接拉进agent team当队友用。角色、工具、模型选择都从subagent定义继承。

这是我最喜欢的一个玩法。一个角色定义一次，既可以作为subagent被主代理调用，也可以作为agent team的队友。不用重复写系统提示。

实际落地场景：团队里固定会用的security-reviewer、test-runner、doc-updater这几个角色，一次性写好subagent定义。日常单任务需要快速审查时把它当subagent调；碰到复杂场景要开team时，同一批角色直接当队友拉起。维护成本降到最低。

我在 ~/.claude/agents/security-reviewer.md 帮你建好了一个示例：

---
name: security-reviewer
description: Security-focused code reviewer. Use for auditing code...
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a security-focused code reviewer. Your job is to audit code
for security vulnerabilities.

Focus areas:
- OWASP Top 10 (injection, broken auth, sensitive data exposure...)
- Credential and secret handling
- Input validation and sanitization
- Authentication and authorization flows
- Cryptographic operations

Output format:
1. Findings grouped by severity: CRITICAL / HIGH / MEDIUM / LOW
2. Each finding includes file:line, vulnerability type, repro, fix
3. End with an executive summary

引用时直接在prompt里报名字：

Spawn a teammate using the security-reviewer agent type to audit src/auth/. Also spawn a general-purpose teammate to cross-check the findings.

实测分工：subagent定义文件已经写进你本地的 ~/.claude/agents/security-reviewer.md，可以直接用。把它拉进team当队友跑一次是你的动作。

并行工作的最佳实践

跑过几个团队之后总结的几条经验，结合官方建议。

给队友足够的context。队友自动加载项目级的CLAUDE.md、MCP servers和skills，但不会继承lead的对话历史。在生成prompt里要把任务相关的关键信息写清楚，特别是文件路径、模块约定、技术栈细节。

团队规模3到5个最合适。再多协调开销和token成本就指数上升，3到5个队友做5到6个任务每人是经过验证的甜蜜点。如果有15个独立小任务，3个队友是一个好起点，让队友各自轮转处理。

任务粒度要恰到好处。太小协调开销超过收益；太大队友长时间不check浪费风险高。理想粒度是一个自包含的可交付单元（一个函数、一个测试文件、一份审查）。

等队友完成再继续。lead有时会自己开始干活而不是等队友。如果发现这种情况，直接告诉它 "wait for your teammates to complete their tasks before proceeding"。

从研究和审查类任务入手。新手第一次开团，建议从不需要写代码的任务开始（PR审查、库调研、Bug调查），这种任务边界清楚、不涉及并行实施的协调挑战，能直观感受到Agent Teams的价值。

避免文件冲突。两个队友编辑同一个文件会互相覆盖。任务拆分时保证每个队友拥有独立的文件集。

主动监控和指导。让团队无人值守跑太久会浪费成本。中途用 Ctrl+T 看任务列表，发现方向跑偏直接Shift+Down过去重定向。

踩坑提醒

几个官方列出的已知限制+我自己撞过的坑：

In-process模式的队友不支持 /resume 和 /rewind。恢复会话后，lead可能会尝试给已经不存在的队友发消息，让它重新生成新队友就行。

任务状态偶尔会滞后。队友有时没能把任务标记成completed，会阻塞依赖任务。卡住了手动改状态或者让lead push。

关闭比较慢。队友要先完成当前的请求或工具调用才会退出。

一个会话同时只能带一个team，不能嵌套team。lead创建了就是lead，中途不能转职。

token消耗3到4倍，能单会话搞定的别硬开团，能用subagents解决的别硬凑团队。

最容易撞上的坑：team怎么都开不起来。prompt跑下去仍然是 Running N agents... 这种subagents形态。按顺序自查：

prompt里有没有显式用 agent team / teammate 关键词（启动章节强调过的）
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 在当前shell里是不是 1（开启章节那个 "1" vs "true" 的坑）
改完settings.json有没有完全退出Claude Code重开
跑完prompt后 ls ~/.claude/teams/ 看下目录有没有生成新team。有目录才是真触发了，这是判断的最硬标准

四条都对上team还没起来，就用 claude --debug -d "agent|team" 看日志，或者去 github.com/anthropics/claude-code/issues 搜相似报告。

最后

Agent Teams本质上是Claude Code CLI工具层在多智能体协作上的一套工程化实现。3到5人的小团队规模、开发者能看懂每一步的透明度、本地直接跑不依赖云端，这些是它的核心定位。

如果你的任务到了几百个sub-agent并发那种量级（比如一次性生成30个落地页、批量匹配100个岗位生成简历），可以去看看Kimi K2.6刚发的Agent Swarm（入口 kimi.com/agent-swarm），走的是另一条云端大规模分解的路。两者定位不重合，按场景选就是了。

把上面这套流程过一遍：先判断是不是该开团，再启动，再用控制操控里的快捷键和模式去介入，跑完按最佳实践做监控和清理。三个案例我准备好了素材，你按顺序跑一遍基本上就上手了。

先聊到这里。

参考文献

Orchestrate teams of Claude Code sessions（官方英文文档）, Anthropic, https://code.claude.com/docs/en/agent-teams
协调 Claude Code 会话团队（官方中文文档）, Anthropic, https://code.claude.com/docs/zh-CN/agent-teams
用Subagents打造Claude Code专业开发团队, 鲁工, https://mp.weixin.qq.com/s/fgEIZIkyttOpeRE3DGoMgA
Kimi K2.6: Advancing Open-Source Coding, Moonshot AI, https://www.kimi.com/blog/kimi-k2-6

整体看下来，Agent Teams是Claude Code在Subagents之上又往前了一大步，把"多个独立工作者"升级成了"能互相讨论的团队"。值得花点时间真上手玩一玩。

本文首发于微信公众号「AI编程实验室」