agents 插件市场 Agent Teams 的 /team-review 实战指南：多维度并行代码审查与报告合并

/team-review 是 agents 插件市场中 agent-teams 插件提供的多评审者并行代码审查命令：它把一次审查拆解为安全、性能、架构、测试、无障碍等独立维度，为每个维度生成一个专职评审 Agent 并行工作，最终合并、去重并输出按严重级别组织的统一报告。读完本文，你将掌握该命令的完整参数、五阶段执行流程、评审维度的检查清单与严重程度校准规则，并理解其背后的团队生命周期、任务编排与优雅关闭机制。

一、命令定位与前置条件

/team-review 的定义文件为 plugins/agent-teams/commands/team-review.md，其 frontmatter 声明了命令描述与参数提示：

description: "Launch a multi-reviewer parallel code review with specialized review dimensions"
argument-hint: "<target> [--reviewers security,performance,architecture,testing,accessibility] [--base-branch main]"

即命令接受三类输入：

• <target>：审查目标，可以是文件路径、目录、git diff 范围（如 main...HEAD）或 PR 编号（如 #123）；
• --reviewers：逗号分隔的审查维度，默认 security,performance,architecture，可选全集为 security,performance,architecture,testing,accessibility；
• --base-branch：diff 对比的基准分支，默认 main。

命令执行前有两项 Pre-flight Checks：

1. 验证环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 已设置——Agent Teams 是 Claude Code 的实验特性，未启用时命令不会执行（这一点与 team-spawn 命令 的前置检查一致，均要求该实验特性标志）；
2. 解析 $ARGUMENTS，提取上述三个参数。

插件级前置配置见 plugins/agent-teams/README.md：需要设置 teammateMode（tmux 推荐、iterm2 仅 macOS、in-process 为默认）以决定每个 teammate 的展示方式，并先添加 marketplace 再执行 /plugin install agent-teams@claude-code-workflows 安装插件。

二、Phase 1：目标解析（Target Resolution）

命令的第一步是把用户输入统一解析为「待审查文件清单 + 完整 diff 内容」，因为这是分发给各评审者的原料。按目标类型分三种路径：

• 文件/目录：直接作为审查范围使用；
• Git diff 范围：通过 Bash 执行 git diff {range} --name-only 获取变更文件列表；
• PR 编号：通过 Bash 执行 gh pr diff {number} --name-only 获取变更文件列表。

随后命令收集完整 diff 内容用于分发给各评审者，并向用户展示审查范围摘要，格式为 "{N} files to review across {M} dimensions"（N 为文件数、M 为维度数）。这一步保证了后续所有评审者基于完全相同的 diff 快照工作，避免并行审查时各看各的代码状态。

三、Phase 2：团队生成（Team Spawn）

这是 /team-review 的核心编排步骤，完全复用了 Agent Teams 的团队生命周期协议（定义于 team-lead agent 的 Team Lifecycle Protocol：Spawn → Assign → Monitor → Collect → Synthesize → Shutdown → Cleanup）：

1. 使用 TeamCreate 工具创建团队，team_name 取 "review-{timestamp}"（时间戳后缀避免与已有团队重名），并附 description；
2. 对每个请求的审查维度，用 Agent 工具生成一个 teammate，关键参数为：
   • name：{dimension}-reviewer，例如 security-reviewer、performance-reviewer；
   • subagent_type：agent-teams:team-reviewer，即插件内置的专职多维护评审者；
   • prompt：包含维度分配、目标文件清单和 diff 内容；
3. 用 TaskCreate 为每个评审者建立任务：
   • Subject："Review {target} for {dimension} issues"；
   • Description：包含文件列表、diff 内容和该维度专属的检查清单。

team-reviewer：被生成者的职责边界

subagent_type 指向的 team-reviewer agent 定义 规定了评审者的能力边界。其 frontmatter 声明了工具白名单与模型：

tools: Read, Glob, Grep, Bash, TaskList, TaskGet, TaskUpdate, SendMessage
model: opus
color: green

即评审者拥有只读代码探索工具（Read/Glob/Grep）、执行能力（Bash）、任务状态工具（TaskList/TaskGet/TaskUpdate）和团队通信工具（SendMessage）。其中 SendMessage、TaskList 等通信/任务工具在受限工具白名单下必须显式列出，否则 teammate 无法收到消息或汇报进度（这是 team-communication-protocols skill Troubleshooting 一节明确列出的排障要点）。

该 agent 定义了五个维度的完整审查关注点，这正是 --reviewers 参数的取值全集：

• Security：输入校验与清洗、认证授权检查、SQL 注入/XSS/CSRF、密钥泄露、依赖已知 CVE、不安全加密用法、访问控制绕过、API 安全（限流、输入边界）；
• Performance：数据库查询效率（N+1、缺失索引、全表扫描）、内存分配与泄漏、冗余计算、缓存机会与失效策略、异步并发正确性、资源清理与连接管理、算法复杂度、Bundle 体积与懒加载；
• Architecture：SOLID 遵循、关注点分离与层边界、依赖方向与循环依赖、API 契约设计与版本化、错误处理策略一致性、配置管理、抽象恰当性（过度/不足工程）、模块内聚与耦合；
• Testing：关键路径覆盖缺口、测试隔离与确定性、Mock 恰当性、边界条件覆盖、集成测试完备性、命名清晰度、断言质量、可维护性与脆弱性；
• Accessibility：WCAG 2.1 AA 合规、语义化 HTML 与 ARIA、键盘导航、屏幕阅读器兼容、色彩对比度、焦点管理与 Tab 顺序、媒体替代文本、响应式与缩放支持。

每条发现必须使用统一的结构化格式输出，包含 Location（path/to/file.ts:42 形式的具体文件:行号）、Dimension、Severity（Critical/High/Medium/Low）、Evidence（含代码片段）、Impact 与 Recommended Fix。这一格式是 Phase 4 能自动去重合并的前提——没有 file:line 定位就无法做位置级合并。

此外 agent 定义了明确的行为约束：严格停留在被分配维度内不越界、每条发现必须引用具体 file:line、严重程度评级必须基于证据而非主观、区分「确认问题」与「潜在顾虑」、通过核实上下文避免误报，并且「无发现的维度要如实报告 no findings，不得凑数」。

更细粒度的逐维度检查清单（可勾选的 checklist）存放在 review-dimensions.md，例如安全维度下的输入处理（参数化 SQL、HTML 转义、路径穿越防护、请求大小限制）、认证授权（JWT 校验签名/过期/签发者、bcrypt/argon2 哈希）、密钥与配置（无硬编码密钥、.gitignore 覆盖敏感文件）、依赖（无已知 CVE、版本固定）等，正是 TaskCreate 时写入任务 Description 的「维度专属检查清单」内容来源。

维度选择建议

multi-reviewer-patterns skill 给出了维度分配与推荐组合，可直接用于决定 --reviewers 的取值：

场景	推荐维度组合
API 端点变更	Security, Performance, Architecture（命令默认值）
前端组件	Architecture, Testing, Accessibility
数据库迁移	Performance, Architecture
认证变更	Security, Testing
完整功能审查	Security, Performance, Architecture, Testing

各维度的「何时启用」原则：Security 凡是处理用户输入或认证就应包含；Performance 在改动数据访问或热路径时包含；Architecture 在结构性变更或新增模块时包含；Testing 在添加新功能时包含；Accessibility 在 UI/前端变更时包含。

四、Phase 3：监控与收集（Monitor and Collect）

命令进入等待期：

1. 周期性检查 TaskList，等待所有审查任务完成；
2. 每个评审者完成后即收集其结构化发现（前文 team-reviewer 的输出格式）；
3. 跟踪进度，以 "{completed}/{total} reviews complete" 形式向用户反馈。

用户也可以主动用 /team-status 命令查看团队状态——它读取 ~/.claude/teams/{team-name}/config.json 并用 TaskList 拉取任务状态，展示成员表（名字、角色、当前任务）与任务表（ID、状态、负责人、主题、进度百分比），支持 --tasks、--members、--json 过滤。从源码结构看，团队配置文件存放在 ~/.claude/teams/{team-name}/config.json，其中 members 数组列出每个成员的 name、agentId、agentType；所有消息与任务指派一律使用 name 而非 UUID，这是 team-lead 通信协议 的硬性要求。

五、Phase 4：结果合并（Consolidation）

这是 /team-review 相对「多个评审者各自出报告」的关键增值步骤，对应 multi-reviewer-patterns skill 中「Finding Deduplication」一节的四条规则：

1. Deduplicate（去重）：合并引用同一 file:line 位置的发现。skill 中的完整合并规则为：同位置同问题 → 合并为一条并标注所有评审者；同位置不同问题 → 保留为独立发现（标记为 "co-located"）；同问题不同位置 → 分开保留但交叉引用；
2. Resolve conflicts（冲突消解）：当评审者对严重级别判断不一致时，取更高的评级；对修复建议冲突时，两条建议都保留并标注评审者归属；
3. Organize by severity（按严重级别分组）：Critical → High → Medium → Low 四级分组；
4. Cross-reference（交叉引用）：标注出现在多个维度中的发现——一条发现被多个独立维度命中，往往意味着它确实是高置信度问题。

严重级别的校准基准同样来自 multi-reviewer-patterns skill：

级别	影响	可能性	典型示例
Critical	数据丢失、安全失陷、完全失败	必然或极可能	SQL 注入、认证绕过、数据损坏
High	功能显著受损、性能退化	很可能	内存泄漏、缺失校验、流程中断
Medium	部分影响、有绕行方案	可能发生	N+1 查询、边界用例缺失、错误信息不清
Low	影响极小、纯外观	不太可能	风格问题、微小优化、命名

并配有硬性校准规则：外部用户可利用的安全漏洞一律 Critical 或 High；热路径性能问题至少 Medium；关键路径缺测试至少 Medium；核心功能的无障碍违规至少 Medium；无功能影响的风格问题为 Low。

六、Phase 5：报告与清理（Report and Cleanup）

命令最后输出合并后的统一报告，team-review.md 中定义的报告模板为：

## Code Review Report: {target}

Reviewed by: {dimensions}
Files reviewed: {count}

### Critical ({count})
[findings...]

### High ({count})
[findings...]

### Medium ({count})
[findings...]

### Low ({count})
[findings...]

### Summary
Total findings: {count} (Critical: N, High: N, Medium: N, Low: N)

其中每条 finding 遵循 team-reviewer 的结构化格式（标题 + Location + Dimension + Severity + Evidence + Impact + Recommended Fix）。skill 中还提供了更完整的报告模板变体，包含按维度 × 严重级别的统计汇总表（如 | Security | 1 | 2 | 3 | 0 | 6 |）与总体推荐行动项，可作为生成报告时的增强参考。

报告输出后进入清理：

1. 向所有评审者发送 shutdown_request 消息。按 team-communication-protocols 的 Shutdown Protocol，评审者会以 shutdown_response 回应（approve: true 则保存状态退出；approve: false 附原因则继续工作，lead 需等待其完成后重试，绝不强制终止有未保存工作的 teammate）；
2. 调用 TeamDelete 移除团队资源（团队目录与任务目录）。

如果希望保留任务清单供后续分析，也可改用通用的 /team-shutdown 命令并加 --keep-tasks 参数，任务列表将保留在 ~/.claude/tasks/{team-name}/；--force 参数则跳过对优雅关闭响应的等待。

七、完整使用示例与配套命令

结合 agent-teams README 的 Quick Start，典型的审查流程如下：

# 对 src/ 目录做三维度审查（默认组合：security,performance,architecture）
/team-review src/ --reviewers security,performance,architecture

# 对 main 到 HEAD 的 diff 做全维度审查
/team-review main...HEAD --reviewers security,performance,architecture,testing --base-branch main

# 审查某个 PR
/team-review #123 --reviewers security,testing

执行过程中与收尾阶段的配套命令：

命令	作用
/team-status	查看成员、任务与进度，支持 --json 原始输出
/team-delegate	任务委派与负载管理（--rebalance 可在负载不均时再平衡）
/team-shutdown	优雅关闭团队并清理资源（--force / --keep-tasks）
/team-spawn review	用预设直接生成 3 评审者团队（security/performance/architecture 维度、默认队名 review-team），适合需要更长生命周期的场景

从 team-spawn 命令定义 可确认 review 预设与 /team-review 的默认维度一致：生成 3 个 team-reviewer agent 并分配 security、performance、architecture 三个维度。区别在于 /team-spawn review 生成的是可长期监控、可追加任务的团队，而 /team-review 是端到端一次性流水线：解析 → 生成 → 监控 → 合并 → 报告 → 清理，全部自动完成。

八、设计要点小结

• 维度即角色：--reviewers 的每个取值对应一个独立 teammate（{dimension}-reviewer），评审者被硬性约束在单一维度内工作，从结构上避免了「一个全知评审者」注意力稀释的问题；
• 统一输出格式是自动合并的前提：每条发现携带 file:line 定位与四级严重度，使 Phase 4 的位置级去重和级别冲突消解（取高评级）可以机械执行，而不依赖语义猜测；
• 并行但同源：所有评审者基于 Phase 1 收集的同一份 diff 快照工作，进度通过 TaskList/TaskUpdate 追踪，通信协议要求状态更新走任务系统而非结构化 JSON 消息；
• 生命周期闭环：TeamCreate 到 TeamDelete 全程由命令自动管理，shutdown_request/shutdown_response 握手保证没有未保存工作的评审者被强杀，团队资源不会泄漏在 ~/.claude/teams/ 下。

需要再次强调的适用前提：该命令依赖 Claude Code 的实验特性，必须设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1；<target> 为 PR 编号时依赖本机 gh CLI 可用；diff 范围参数依赖标准 git 命令。审查维度、检查清单与校准规则均可在 plugins/agent-teams/skills/multi-reviewer-patterns 与 plugins/agent-teams/agents/team-reviewer.md 中继续深入查阅。