Appearance
Review 详细指南
概述
Review 是 Spec-First 工作流的第四步，目标是确保质量。
输入： 实施产物（代码 + 测试） 输出： 评审报告（内嵌在会话中）+ 可选的自动修复
通过这个阶段，Spec-First 使用 26 个专业评审代理从不同维度审查代码。
三种模式
| 模式 | 命令 | 行为 |
|---|---|---|
| Interactive（默认） | /spec:review | 评审 → 展示发现 → 询问决策 → 可选修复 |
| Autofix | /spec:review mode:autofix | 无交互，只自动修复 safe_auto 问题，其余生成 Todo |
| Report-only | /spec:review mode:report-only | 只读报告，不修改任何文件 |
Autofix 模式规则：
- 跳过所有用户问题
- 只修复
safe_auto级别的问题 - 不提交、不推送、不创建 PR
- 未解决的问题生成 Todo 文件
Report-only 模式规则：
- 严格只读
- 不写文件、不创建 Todo、不提交
- 可安全与浏览器测试并行运行
分层评审人系统
Review 使用 26 个专业代理，按需选择：
Always-on（每次审查必启）
| 代理 | 关注领域 |
|---|---|
| correctness-reviewer | 逻辑错误、边界情况、状态 bug |
| testing-reviewer | 覆盖缺口、断言质量、脆弱测试 |
| maintainability-reviewer | 耦合、复杂度、命名、死代码 |
| project-standards-reviewer | CLAUDE.md / AGENTS.md 合规性 |
| code-simplicity-reviewer | 代码简洁性、YAGNI 原则 |
| pattern-recognition-specialist | 设计模式、反模式、命名规范 |
条件触发（按变更内容选择）
| 代理 | 触发条件 |
|---|---|
| security-reviewer | 认证、公共端点、用户输入 |
| performance-reviewer | 数据库查询、缓存、异步处理 |
| data-migrations-reviewer | 迁移文件、schema 变更 |
| reliability-reviewer | 错误处理、重试、超时 |
| architecture-strategist | 架构模式、服务边界 |
| adversarial-reviewer | 大型变更（≥50 行）或高风险区域 |
| dhh-rails-reviewer | Rails 架构决策 |
| kieran-typescript-reviewer | TypeScript 代码 |
| kieran-python-reviewer | Python 代码 |
严重度等级（P0-P3）
所有评审人统一使用四级严重度：
| 等级 | 含义 | 动作 |
|---|---|---|
| P0 | 关键破坏、安全漏洞、数据丢失 | 必须修复后才能合并 |
| P1 | 高影响缺陷，正常使用可能触发 | 应该修复 |
| P2 | 中等问题（边界情况、性能回退） | 如果简单就修复 |
| P3 | 低影响，小范围改进 | 用户自行决定 |
操作步骤
步骤 1: 启动 Review
bash
# 默认交互模式
/spec:review
# 自动修复模式
/spec:review mode:autofix
# 只读报告模式
/spec:review mode:report-only
# 指定 PR
/spec:review 42
# 指定基准分支
/spec:review base:origin/main
# 指定计划文档（用于需求验证）
/spec:review plan:docs/plans/2026-03-30-001-feat-auth-plan.md步骤 2: 确定范围（Stage 1-2）
- 计算变更范围（diff、文件列表）
- 从 PR 标题/提交信息提取意图
- 如提供计划文档，自动进行需求验证
步骤 3: 选择评审人（Stage 3）
基于变更内容选择评审人组合，展示评审团队。
步骤 4: 并行审查（Stage 4）
所有评审人并行执行，各自返回结构化 JSON 结果。
步骤 5: 合并去重（Stage 5）
- 置信度过滤（低于 0.60 的发现被抑制）
- 指纹去重（同一文件 ±3 行的相似发现合并）
- 路由归一化（不一致时取更保守的路由）
步骤 6: 展示报告（Stage 6）
报告包含：
- 范围和意图 — 本次审查覆盖的内容
- 按严重度分组的发现 — P0 → P3
- 需求验证 — 与计划文档的对照（如提供）
- 已自动修复的问题 — autofix 模式下
- 残留待办 — 需要人工处理的问题
- 历史经验 — learnings-researcher 搜索的相关知识
Action Routing
每个发现会被路由到不同的处理方式：
| 路由 | 含义 | 处理者 |
|---|---|---|
| safe_auto | 本地确定性修复 | review-fixer（自动） |
| gated_auto | 有具体修复但涉及敏感边界 | downstream-resolver |
| manual | 需要人工处理的工作 | downstream-resolver |
| advisory | 只读建议（学习、部署注意事项） | 人工参考 |
最佳实践
- ✅ 提供计划文档 — 使用
plan:参数启用需求验证 - ✅ 区分阻断和优化 — P0/P1 必须修，P3 可选
- ✅ 利用 autofix — 简单变更用
mode:autofix自动处理 - ✅ 与 Todo 系统集成 — 未解决的问题自动生成 Todo
常见错误
- ❌ 只看代码不看测试 → ✅ testing-reviewer 专门审查测试
- ❌ 过度关注代码风格 → ✅ 优先关注 P0/P1 功能正确性
- ❌ 不提供计划文档 → ✅ 用
plan:参数启用需求验证 - ❌ autofix 用于高风险变更 → ✅ 高风险场景使用 Interactive 模式
判定标准
完成 Review 后，检查以下条件：
- [ ] 无 P0 问题
- [ ] 无未处理的 P1 问题
- [ ] 功能正确性已验证
- [ ] 测试覆盖充分
- [ ] 评审报告已生成
全部满足后，进入 Compound 阶段。
下一步
阅读 Compound 详细指南 了解如何沉淀知识。