Agent Teams 插件实战：用 Claude Code 编排并行多 Agent 团队完成代码审查、调试与协同开发

Agent Teams 是 agent-teams 插件为 Claude Code 引入的「多智能体团队编排」能力：围绕代码审查、假设驱动调试、并行特性开发、安全审计与代码迁移等高频研发场景，以预设团队或自定义组合的方式编排 2～5 个专职 Agent 并行工作。读完本文，你将掌握该插件的环境配置与安装流程、四类角色（lead / reviewer / debugger / implementer）的分工与工具边界、七个预设团队模板的选型要点，以及 /team-* 系列命令在真实工作流中的完整调用链与最佳实践。

插件定位：为 Claude Code 的 Agent Teams 实验特性提供编排层

agent-teams 是本仓库（一个面向 Claude Code、Codex、Cursor、OpenCode、GitHub Copilot 与 Google Antigravity 的多 harness Agent 插件市场）中围绕 Claude Code 实验性 Agent Teams 特性构建的编排插件。它并不重新发明多 Agent 的底层通信，而是提供「如何组建团队、如何分派任务、如何保证并行不冲突、如何优雅收尾」这套工程化的编排约定。

仓库中该插件的完整组成（plugins/agent-teams/README.md）包括：

• 4 个专职角色：team-lead、team-reviewer、team-debugger、team-implementer（agents 目录）
• 7 个编排命令：/team-spawn、/team-status、/team-shutdown、/team-review、/team-debug、/team-feature、/team-delegate（commands 目录）
• 6 个配套技能：团队构成、任务协调、并行调试、多评审、并行开发、团队通信（skills 目录）

一句话概括价值：把「一个 Agent 串行做完」变成「多个专职 Agent 并行做完，再由 Lead 汇总」，在维度可拆解、文件可切分的场景下显著缩短整体耗时，同时通过严格的 ownership 边界避免并行写码互相踩踏。

环境准备与安装

1. 开启实验特性开关

Agent Teams 是 Claude Code 的实验特性，使用前必须先设置环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

该开关是 team-spawn、team-review、team-debug、team-feature 等命令的前置校验项：例如 team-spawn 命令 的执行逻辑会先验证该变量是否设置，未设置时提示 Agent Teams requires the experimental feature flag... 并停止执行。建议写入 shell 配置文件（如 ~/.bashrc / ~/.zshrc）保证每次会话生效。

2. 配置队友显示模式

在 ~/.claude/settings.json 中配置 teammateMode，决定每个队友（teammate）以何种形态展示：

{
  "teammateMode": "tmux"
}

取值	行为	适用场景
"tmux"	每个队友运行在独立的 tmux 面板中	开发工作流，多 Agent 并行时可逐个面板观察（推荐）
"iterm2"	每个队友获得独立的 iTerm2 标签页	仅 macOS、偏好 iTerm2 的用户
"in-process"	队友在同一个进程内运行	简单任务、CI/CD 或脚本化环境（默认值）

补充一点实操细节（见 team-composition-patterns 技能 的 Troubleshooting）：使用 tmux 模式前请确保 tmux 已安装且已有会话在运行；CI 或无 tmux 环境请退回 in-process。

3. 安装插件

仓库采用插件市场分发方式。若尚未添加市场，先执行：

/plugin marketplace add wshobson/agents

再安装本插件：

/plugin install agent-teams@claude-code-workflows

团队角色模型：四种专职 Agent 的分工与工具边界

角色定义文件存放在 plugins/agent-teams/agents/ 下，每个文件头部以 frontmatter 声明角色名称、描述、可用工具、模型与标识色，正文则是该角色的完整系统提示词。

Agent	角色职责	标志色	关键工具（frontmatter 中声明）	定义文件
team-lead	团队编排者：拆解任务、管理生命周期、汇总结果	Blue	Read / Glob / Grep / Bash / Agent / TeamCreate / TeamDelete / TaskCreate / TaskList / TaskGet / TaskUpdate / SendMessage	agents/team-lead.md
team-reviewer	多维代码评审者：只在自己被分配的质量维度上工作	Green	Read / Glob / Grep / Bash + 任务与消息工具	agents/team-reviewer.md
team-debugger	假设调查员：为「验证/证伪某个假设」收集证据	Red	Read / Glob / Grep / Bash + 任务与消息工具	agents/team-debugger.md
team-implementer	并行开发者：严格遵守文件归属边界实现组件	Yellow	Read / Write / Edit / Glob / Grep / Bash + 任务与消息工具	agents/team-implementer.md

值得注意的差异点（决定你该选哪个角色）：

• team-reviewer 与 team-debugger 都不具备 Write/Edit 工具——评审与调查角色只读代码、产出结论，保证不改动被审查的代码；
• team-implementer 是唯一带写文件能力的专职角色，并通过「文件归属协议」约束自己只改动任务清单中明确指派的文件；
• team-lead 的工具面最广，额外持有 TeamCreate/TeamDelete/TaskCreate 等编排工具，是唯一能创建/销毁团队的角色。

team-lead：团队编排者

team-lead.md 定义了六项核心能力：团队构成（2～5 名队友、匹配预设或自定义、配置显示模式）、任务拆解（产出带验收标准且相互独立的工作单元）、文件归属管理、依赖管理（blockedBy/blocks 关系建依赖图、缩短依赖链深度、消除循环依赖）、结果汇总、冲突仲裁。

该角色内部还有一套硬性的文件归属规则：

1. 每个文件只能有一个 owner，绝不把同一文件分给多个队友；
2. 边界必须显式化——被拥有的文件/目录要在任务描述中逐一列出；
3. 当队友共享边界时，开工前先定义接口契约（类型、API）；
4. 若某文件确实需要多方改动，由 lead 亲自持有并串行应用修改。

通信协议要点：默认用 SendMessage 直接点对点通信；broadcast 仅用于关键的全员广播；不发送结构化的 JSON 状态消息（改用 TaskUpdate）；队友发现从 ~/.claude/teams/{team-name}/config.json 读取；始终用实际 spawn 出来的名字（NAME）引用队友，不要用 UUID 或角色别名。

生命周期协议则固定为七步：Spawn（TeamCreate + Agent 拉起队友）→ Assign（TaskCreate/TaskUpdate 建任务）→ Monitor（周期性 TaskList）→ Collect（收集结果）→ Synthesize（合并输出）→ Shutdown（逐个发 shutdown_request）→ Cleanup（TeamDelete 清理资源）。

team-reviewer：单维深审

team-reviewer.md 要求评审者严格守在被分配的那一个维度内，产出统一结构的发现项，便于多个评审者结果合并。定义中覆盖五个评审维度及其检查清单：

• Security：输入校验、认证鉴权、注入类漏洞（SQLi/XSS/CSRF）、密钥泄露、已知 CVE 依赖、不安全的加密、越权绕过向量、API 安全（限流与输入边界）；
• Performance：N+1 查询、缺索引、全表扫描、内存分配与泄漏、冗余计算、缓存机会与失效、异步/并发正确性、资源清理与连接管理、时空复杂度、包体积与懒加载；
• Architecture：SOLID、关注点分离与分层边界、依赖方向与循环依赖、API 契约设计与版本化、错误处理一致性、配置管理模式、抽象是否过度/不足、内聚与耦合；
• Testing：关键路径覆盖率缺口、测试隔离与确定性、mock 恰当性、边界条件覆盖、集成测试完备性、命名与文档清晰度、断言质量、可维护性/脆弱性；
• Accessibility：WCAG 2.1 AA、语义化 HTML 与 ARIA、键盘导航、读屏兼容、颜色对比度、焦点管理、媒体替代文本、响应式与缩放。

每个发现项遵循固定输出格式：

### [SEVERITY] Finding Title

**Location**: `path/to/file.ts:42`
**Dimension**: Security | Performance | Architecture | Testing | Accessibility
**Severity**: Critical | High | Medium | Low

**Evidence**:
Description of what was found, with code snippet if relevant.

**Impact**:
What could go wrong if this is not addressed.

**Recommended Fix**:
Specific, actionable remediation with code example if applicable.

评审者行为准则值得单独强调：每条结论必须给出 file:line 定位；严重度基于证据而非观点；区分「已确认问题」与「潜在风险」；在没有问题时如实报告 "no findings"，不夸大成果。

team-debugger：证据驱动的假设调查员

team-debugger.md 采用 ACH（竞争性假设分析）方法论。调查协议分七步：理解假设 → 定义证据标准（什么能 CONFIRM / FALSIFY / 属于 AMBIGUOUS）→ 收集一手证据（代码路径、数据流、git 历史）→ 收集佐证（日志、同类 bug、测试覆盖）→ 构造最小复现检验假设 → 评估置信度 → 汇报。

置信度评级：High（>80%）、Medium（50%～80%）、Low（<50%）；每条结论都必须附 file:line 引用与因果链。证据标准里有五条铁律，其中两条最反直觉也最有价值：必须报告削弱自己假设的反证，以及被证伪的假设同样是有价值的产出（negative results）。同时要求调查员严格守在自己的假设范围内，发现指向其他根因的证据时只上报、不擅自切换调查方向。

team-implementer：边界内的并行构建者

team-implementer.md 是并行开发的「施工方」，遵循文件归属协议：

1. 只修改任务中显式指派的文件；
2. 绝不碰共享文件——需要改动时通过消息上报 lead；
3. 只在自己所属目录内新建文件；
4. 接口契约不可变——改动需 lead 批准；
5. 不确定就先问，绝不越界。

在集成点上的行为规范很关键：引用共享契约中定义的类型/接口；不替队友实现对方那一侧（开发期用 stub/mock）；自己一侧的接口就绪后主动消息通知下游队友；发现契约有问题立即上报 lead。实现流程为五阶段：理解任务 → 规划实现 → 构建 → 验证（编译/lint/接口对齐/验收标准）→ 汇报（TaskUpdate 置完成 + 消息总结）。

预设团队与命令全景

七个编排命令定义在 plugins/agent-teams/commands/ 目录：

命令	说明
/team-spawn	用预设（review / debug / feature / fullstack / research / security / migration）或自定义组合拉起团队
/team-status	展示团队成员、任务与进度
/team-shutdown	优雅关闭团队并清理资源
/team-review	多评审者并行代码审查
/team-debug	竞争性假设的并行调试
/team-feature	带文件归属的并行特性开发
/team-delegate	任务委派面板与负载管理

配合 6 个技能库（详见 skills 目录）沉淀「怎么做」的方法论：

技能	覆盖内容
team-composition-patterns	团队规模启发式、预设构成、Agent 类型选择
task-coordination-strategies	任务拆解、依赖图、负载监控
parallel-debugging	假设生成、证据收集、结果仲裁
multi-reviewer-patterns	评审维度分配、发现去重、严重度校准
parallel-feature-development	文件归属策略、冲突规避、集成模式
team-communication-protocols	消息类型选择、计划审批流程、关闭协议

预设团队构成速查

技能 preset-teams.md 提供了每个预设的精确构成，配合 team-spawn 命令 的解析逻辑，可得如下对照表：

预设	默认人数	构成	默认团队名
review	3	3× team-reviewer（security / performance / architecture）	review-team
debug	3	3× team-debugger（每人一个假设）	debug-team
feature	3	1× team-lead + 2× team-implementer	feature-team
fullstack	4	1× lead + frontend / backend / tests 三个 implementer	fullstack-team
research	3	3× general-purpose（各自研究不同问题/区域）	research-team
security	4	4× team-reviewer（OWASP / auth / 依赖供应链 / 密钥与配置）	security-team
migration	4	1× lead（规划）+ 2× implementer（并行迁移流）+ 1× reviewer（正确性验证）	migration-team

团队规模启发式

技能 SKILL.md 给出了按复杂度选规模的参考表：

复杂度	团队规模	适用场景
简单	1～2	单维度评审、孤立 bug、小特性
中等	2～3	多文件改动、2～3 个关注点、中型特性
复杂	3～4	横切关注点、大型特性、深度调试
很复杂	4～5	全栈特性、全面评审、系统性问题

黄金法则：用能覆盖所有必需维度的最小团队起步——每多一个队友都意味着通信开销上升。同技能的 Agent 类型选择还提醒：Explore 与 Plan 是只读 Agent（无法写文件），绝不能把实现类任务派给只读 Agent，这是新手最常见的踩坑点。

快速上手：六大高频工作流

以下均来自 README 的 Quick Start，并结合命令实现补充了幕后机制。

1. 多维并行代码审查（/team-review）

/team-review src/ --reviewers security,performance,architecture

该命令会 spawn 3 个评审者，各自从被分配维度分析代码库，最终合并成按严重度排序的报告。看 team-review.md 的完整流程会更清楚它的工程化程度：

• 目标解析：<target> 支持文件/目录、git diff 区间（如 main...HEAD）、PR 号（如 #123）三种输入；对 diff/PR 类型会先用 Bash 执行 git diff {range} --name-only 或 gh pr diff {number} --name-only 收集变更文件清单与完整 diff；
• 并行评审：对每个维度 spawn 一个 {dimension}-reviewer（subagent_type: agent-teams:team-reviewer），用 TaskCreate 下发「Review {target} for {dimension} issues」任务并附带文件清单与维度 checklist；
• 合并去重：对引用同一 file:line 的发现做去重；评审者对严重度意见不一致时取更高等级；按 Critical / High / Medium / Low 分组，并标注跨维度同时命中的问题；
• 收尾：产出格式化的汇总报告后逐个发 shutdown_request，再 TeamDelete 清理资源。

可选参数：--reviewers 默认 security,performance,architecture，可自由扩展到五维；--base-branch 默认 main。

2. 假设驱动并行调试（/team-debug）

/team-debug "API returns 500 on POST /users with valid payload" --hypotheses 3

命令会生成 3 个竞争性假设、为每个假设拉起调查员、收集证据后给出最可能的根因与修复建议。team-debug.md 定义了六大失败模式类作为假设生成方向：逻辑错误（算法/条件/off-by-one/缺失边界）、数据问题（非法输入/类型不匹配/null/编码）、状态问题（竞态/陈旧缓存/错误初始化/变异 bug）、集成失败（API 契约违反/版本不匹配/配置错误）、资源问题（内存泄漏/连接耗尽/超时/磁盘）、环境问题（缺依赖/版本错误/平台行为）。

关键在 Phase 5 的仲裁（Arbitration）：对比各调查员证据，将假设归类为 confirmed / falsified / inconclusive，再按置信度、因果链强度、支持证据量、无反证四项排序，最终输出带 Confidence、Evidence（含 file:line 引用）、Causal Chain（从因到果逐步推演）的根因分析与针对性修复方案，同时列出其余假设的状态。可选参数：--hypotheses N（默认 3）、--scope files|module|project。

3. 文件归属约束下的并行特性开发（/team-feature）

/team-feature "Add user authentication with OAuth2" --team-size 3 --plan-first

team-feature.md 把一条特性描述拆成多个「工作流（work stream）」，每个流独占文件、定义流间接口契约、用 blockedBy/blocks 表达依赖，最后 spawn 多个 implementer 并行构建。几个实现层面的要点：

• --team-size 控制 implementer 数量（默认 2），lead 不计入；--branch 可指定 git 分支（默认按特性描述自动生成），spawn 前会执行 git checkout -b {branch-name}；
• --plan-first 是推荐流程：先把「Stream 划分 / 各流文件清单 / 依赖关系 / 集成契约」展示给用户审批，批准后才 spawn，避免方向性返工；
• 依赖管理贯穿全程：TaskUpdate 设置 blockedBy，某个 implementer 完成接口后，lead 要主动通知依赖方解除阻塞（unblock）；
• 集成验证：所有任务完成后用 Bash 跑构建与测试，发现问题创建修复任务分派给对应 implementer，最后输出变更摘要（改动文件数、流完成数、测试通过率、所在分支）。

4. 并行研究（/team-spawn research）

/team-spawn research --name codebase-research

spawn 3 个 general-purpose 研究员，各自负责不同问题/区域，可同时进行代码库侧（Grep/Glob/Read）与 Web 侧（WebSearch/WebFetch）调研，每个结论附带引用。从 preset-teams.md 可看到三种常用变体：

• 纯代码库研究：3 人分别探索不同模块/模式；
• 纯 Web 研究：3 人用 WebSearch 调研方案、基准、最佳实践；
• 混合研究（评估新库时推荐）：1 人查代码库 + 1 人查文档 + 1 人查 Web。

任务模板中甚至给出可直接套用的分工样例，例如评估 Next.js 认证方案时：研究员 1 追踪现有 auth 系统登录到 token 校验的完整链路，研究员 2 横向比较 NextAuth / Clerk / Auth0 的定价、DX 与迁移成本，研究员 3 查 NextAuth.js v5 的 JWT 与 session 官方文档。

5. 并行安全审计（/team-spawn security）

/team-spawn security

spawn 4 个安全评审者，分别覆盖：OWASP 漏洞面（注入/XSS/CSRF/反序列化/SSRF）、认证与访问控制（认证/鉴权/会话管理）、依赖供应链（CVE/供应链/过期依赖/许可证风险）、密钥与配置（硬编码密钥/环境变量/调试端点/CORS），产出整合安全报告。可派生变体：快速扫描用 --reviewers owasp,secrets 缩到 2 人；CI/CD 专项可在默认四维上追加第 5 名流水线/部署配置评审者。

6. 代码库迁移（/team-spawn migration）

/team-spawn migration --name react-hooks-migration

spawn 1 个 lead（规划迁移 + 协调）、2 个 implementer（并行迁移流）、1 个 reviewer（验证迁移正确性）。依赖模式为 migration-lead(plan) → migrator-1 / migrator-2 → migration-verify。典型适用：框架升级（React class→hooks、Vue2→Vue3、Angular 版本升级）、语言迁移（JS→TS、Py2→3）、API 版本升级（REST v1→v2、GraphQL schema）、ORM/数据库重构、构建系统切换（Webpack→Vite、CRA→Next.js）。任务模板中要求同时给出 Migration rules、Old pattern、New pattern，确保两条迁移流风格一致、可被 reviewer 统一校验。

7. 自定义团队（/team-spawn custom）

/team-spawn custom --name my-team --members 4

team-spawn.md 对 custom 流程的定义是：先用 AskUserQuestion 询问团队规模（2～5 人），再逐个询问成员角色（team-lead / team-reviewer / team-debugger / team-implementer），最后确认团队名。另有 --delegate 标志可在 spawn 后直接进入委派模式。

命令共有的 spawn 注意事项：创建成员时使用 Agent 工具并传 team_name、唯一描述性 name（如 frontend-impl，不要用角色名 team-lead 当成员名）、subagent_type（agent-teams:team-lead 等，research 用 general-purpose）与携带完整上下文的首条 prompt。队友以全新会话启动、无历史记忆，所有相关信息必须写进初始 prompt，这是「队友收不到任务」类问题的首要排查点。

团队的日常管理：状态、委派与优雅关闭

/team-status —— 进度可视化

team-status.md 会做团队发现（给定名字直接用；否则扫描 ~/.claude/teams/；存在多个团队且未指定时列出并请用户选择），然后渲染成员表与任务表：成员状态如 security-rev team-reviewer working on task #2，任务表含 ID / 状态（completed、in_progress、pending）/ Owner / Subject，并计算 Progress: 40% (2/5 completed)。可选 --tasks、--members 只显示单类信息，--json 输出原始 JSON（便于脚本消费）。

/team-delegate —— 任务委派与负载均衡

team-delegate.md 是一个委派仪表盘，支持三种动作：

• --assign task-id=member-name：用 TaskUpdate 设置任务 owner，并 SendMessage 通知被指派人；
• --message member-name 'content'：向指定成员发送消息；
• --rebalance：先分析负载——按 in_progress + pending 统计各成员任务数，找出 0 任务（idle）与 3+ 任务（overloaded）的成员，检查可解锁的阻塞任务，生成如下建议，经用户确认后才执行：

## Workload Analysis

Member          Tasks    Status
─────────────────────────────────
implementer-1   3        overloaded
implementer-2   1        balanced
implementer-3   0        idle

Suggestions:
1. Move task #5 from implementer-1 to implementer-3
2. Assign unassigned task #7 to implementer-3

不带动作标志时显示完整仪表盘（未分配任务 / 成员负载 / 被阻塞任务及其 owner 与依赖链 / 分配建议）。

/team-shutdown —— 优雅关闭

team-shutdown.md 强调用命令关闭而非手动 kill 进程：对有 in-progress 任务的团队先警告并列出任务、征询用户确认；随后向每个成员发 shutdown_request 并等待响应（成员可拒绝，此时向用户报告原因）；最后输出关闭汇总（shut down 数、任务完成数/剩余数）。--force 可跳过优雅等待；--keep-tasks 可保留任务清单于 ~/.claude/tasks/{team-name}/，否则调用 TeamDelete 清理团队与任务目录。

通信与写作协议：让多 Agent 协作不失控

插件为跨 Agent 通信沉淀了明确协议。除前述 team-lead 的通信规范外，实践中值得记住的协作惯例还包括：

• 消息按类型区分用途：默认点对点 message 用于任务交流，broadcast 仅在全员级关键通知时使用，shutdown_request 专用于关闭流程；
• 结构化状态一律走 TaskUpdate，不要让队友靠解析消息里的 JSON 判断状态；
• 跨实现者边界协作时，接口契约先行、契约不可单方变更、对方一侧用 stub 顶替等待就绪通知；
• 共享文件必须由 lead 亲自串行持有，任何 implementer 不得直接改共享文件。

这些约定分别沉淀在 team-communication-protocols 与各角色的行为准则中，是让「并行」不至于变成「互相覆盖」的关键制度设计。

最佳实践清单

README 末尾给出了七条可落地的最佳实践，其中前六条是插件使用者的核心心法：

1. 从预设起步——先用 /team-spawn review|debug|feature 这类预设跑通流程，再构建自定义团队；
2. 特性开发务必 --plan-first——拆解方案先过目再放行 implementer，杜绝方向性浪费；
3. 文件归属是生命线——同一文件绝不派给两个 implementer，边界处用接口契约衔接；
4. 用 /team-status 持续监控——定期查看进度，负载不均时用 /team-delegate --rebalance 调平；
5. 优雅关闭——收尾一律走 /team-shutdown，不要手动杀进程；
6. 团队保持精简——2～4 名队友最优，更大的团队会显著推高协调开销；
7. 善用 Shift+Tab——Claude Code 内置的委派模式（Shift+Tab）可与本插件命令互补，处理临时性的即席委派。

另外补充两个来自技能库的实战提示：一是合并单人维度控制规模（4 人做 6 项独立任务，通常不如 3 人各承担 2 项）；二是当多个评审者反复报出同一问题时，先检查评审维度是否重叠，重新划清各人关注面（正确性/逻辑、安全、性能/扩展性），重叠评审既烧 token 又制造重复发现。

小结

agent-teams 插件把 Claude Code 的 Agent Teams 实验特性封装成了可直接上手的研发工作流：用 team-lead 拆解与仲裁，用 team-reviewer / team-debugger 在各自维度或假设上做深而互不干扰的只读分析，用 team-implementer 在严格文件归属与接口契约约束下并行产出代码，再用状态、委派、关闭三件套把团队生命周期管到底。无论你面对的是多维度代码审查、成因不明的疑难 bug、可拆分的特性开发，还是横跨整个仓库的技术栈迁移，都可以先对照本文的预设构成与最佳实践，从一条 /team-spawn 或 /team-review 命令开始，把单线程的 Agent 会话升级成有组织、有边界的多 Agent 并行流水线。