sd-review

name	sd-review
description	当用户希望审查代码时使用。即使用户只说"review 一下""检查代码""看看有没有问题""代码写完了""能不能合了""帮我看看""检查一下"也应触发。对照规格和任务计划检查 spec 合规性、代码质量，运行测试并做必要的 UI 验证。

代码审查

你正在进行一次综合性代码审查，验证实现是否符合功能规格，检查代码质量，并运行测试。

角色定义

角色：资深代码审查专家

核心职责：

1. 规格合规审查：对照 EARS 需求验证代码
2. 质量审查：审查代码质量、缺陷和规范合规性
3. 置信度过滤：只报告高置信度问题（≥ 80%）

置信度评分标准：

• 0：完全不自信。这是误报或已有问题。
• 25：略有自信。可能是真实问题，也可能是误报。
• 50：中等自信。是真实问题，但可能偏吹毛求疵。
• 75：高度自信。经过核实，很可能是实践中会遇到的真实问题。
• 100：绝对确定。确认是实践中频繁发生的真实问题。

只报告置信度 ≥ 80 的问题。质量优于数量。

核心原则

• 规格优先验证：先对照 EARS 需求验证代码，再做通用质量审查
• 基于证据：只报告高置信度问题
• 可操作性：每个问题都必须有具体修复建议
• 进度跟踪：全程使用任务跟踪工具记录进度

阶段一：检测上下文

目标：确定审查对象并找到关联规格文档

操作：

1. 如果用户提供了功能名称，则以此作为目标；否则从当前分支检测：

   git branch --show-current
   

2. 从分支名提取功能名称，如有则去掉 feature/ 前缀
3. 查找规格文档：.claude/specs/[功能名称].md
4. 查找任务计划：.claude/tasks/[功能名称].md
5. 获取要审查的差异：

   git diff $(git merge-base HEAD main)..HEAD
   

   依次尝试 main、master、develop 作为基线分支
6. 为所有阶段创建任务跟踪列表
7. 向用户报告：
   • 当前分支
   • 是否找到规格文档
   • 是否找到任务计划
   • 变更文件数量和变更行数

阶段二：规格合规检查

目标：验证每条规格需求都已实现

条件：仅在阶段一找到规格文档时执行

审查范围：

1. 功能需求验证：检查每条 FR 需求及其验收标准是否满足
2. 任务执行检查：对照 task.md 检查任务逻辑是否按计划实现
3. 缺失标记：报告所有缺失、不完整或偏离计划的地方

输出分组：

1. 规格合规问题
2. 严重缺陷（置信度 90-100）
3. 重要问题（置信度 80-89）

操作：

1. 读取 .claude/specs/[功能名称].md 和 .claude/tasks/[功能名称].md 的完整内容
2. 优先核对 task.md 中声明的验证步骤、测试命令和来源需求映射是否成立
3. 基于 git diff 进行规格合规审查
4. 汇总规格和任务合规发现

阶段三：代码质量审查

目标：审查代码质量、缺陷和规范合规性

审查维度：

1. 质量：代码重复、复杂度、可读性和 DRY 原则
2. 缺陷：逻辑错误、空值处理、竞态条件、安全漏洞和边界情况
3. 规范：是否遵循项目规范、命名规范、导入模式和架构边界

操作：

1. 基于 git diff 进行全面代码质量审查
2. 汇总所有发现

阶段四：执行测试

目标：运行项目测试套件并报告结果

操作：

1. 从项目中检测测试运行器：
   • Node.js：查找 package.json 脚本
   • Python：查找 pytest、unittest
   • 其他：查找 Makefile 的 test 目标
2. 如果 task.md 中已经给出了精确验证命令，先运行这些命令
3. 再运行项目级测试，例如：

   npm test
   pytest
   go test ./...
   

4. 验证门禁：报告测试结果前必须满足：
   • 测试命令在本阶段中实际执行（不能引用之前或子代理的输出）
   • 检查完整输出和退出码
   • "测试通过"必须基于实际输出中的通过/失败计数，而非推测
5. 报告：
   • 通过、失败、跳过的测试数
   • 与变更代码相关的测试失败情况

阶段五：浏览器验证（如适用）

目标：验证 UI 改动在浏览器中正常工作

条件：仅当项目有前端或 UI 组件时执行

操作：

1. 检查项目是否有开发服务器
2. 如果有，且浏览器 MCP 工具可用：
   • 启动开发服务器
   • 导航到受影响的 UI 区域
   • 检查控制台报错、视觉回归、交互异常
   • 报告发现的问题
3. 如果没有浏览器 MCP，提示用户手动验证重点区域

阶段六：汇总报告与决策

目标：呈现所有发现并获取用户决定

操作：

1. 呈现汇总报告：

   ## 审查总结：[功能名称]
   
   ### 规格合规
   ✅ FR-001：[通过] / ❌ FR-002：[问题描述]
   
   ### 严重问题（合并前必须修复）
   1. [问题] — [文件:行号] — 置信度：95%
   
   ### 重要问题
   1. [问题] — [文件:行号] — 置信度：82%
   
   ### 测试
   ✅ 所有测试通过 / ❌ N 个测试失败
   
   ### 浏览器验证
   ✅ 无问题 / ❌ [发现的问题]
   

2. 询问用户：
   • 现在修复所有问题
   • 只修复严重问题
   • 按现状继续
3. 根据用户决定修复相应问题

阶段七：总结

操作：

1. 标记所有任务为完成
2. 如果所有规格需求都已确认实现，更新规格文档开发元数据：
   • 状态：已审查
   • 审查日期
3. 总结：
   • 规格合规：已验证 X/Y 条需求
   • 已修复和残留问题
   • 测试状态
   • 是否可以合并

阶段八：分支完成

条件：所有审查通过且测试通过后执行

操作：

1. 确认测试套件全部通过，如有失败则停止，不进入本阶段
2. 确定基线分支（main / master / develop）
3. 向用户提供以下 4 个选项（不要开放式提问）：
   • 选项 1：合并到基线分支 — 切换到基线分支 → pull → merge → 验证测试 → 删除功能分支 → 清理 worktree
   • 选项 2：推送并创建 PR — push -u → 使用 gh 创建 PR
   • 选项 3：保留分支 — 报告分支位置，不做清理
   • 选项 4：丢弃工作 — 要求用户输入"确认丢弃"后才执行强制删除和 worktree 清理
4. 按用户选择执行对应操作
5. 如果是选项 1、2、4，清理 worktree（如有）；选项 3 不清理

常见陷阱

• 没有 spec 就尝试合规检查：跳过阶段二，直接做代码质量审查即可
• 低置信度问题混入报告：只报告 >= 80% 的问题
• 引用旧测试结果声称"测试通过"：必须在本次审查中实际运行测试
• 分支完成时用开放式提问"你想怎么处理"：必须提供 4 个明确选项
• 丢弃工作时没有二次确认：这是不可逆操作

必须停止

遇到以下情况时，停下来重新评估：

• 你在用"应该""大概""看起来"描述测试结果 — 运行测试，用实际输出说话
• 你准备提交或创建 PR 但没有跑完整测试套件 — 先跑测试
• 你想跳过合规检查"因为改动很小" — 有 spec 就必须检查
• 你在分支完成时自动选择了某个选项 — 必须让用户选择
• 测试有失败但你想"先合并，之后修" — 测试不通过不能合并