用途:对 HEAD 与用户指定固定点之间的 diff 做双轴评审。固定点可以是 commit SHA、分支名、标签、main、HEAD~5 等;未指定时需向用户询问。
主要能力:
- 规范轴:检查代码是否符合仓库文档化的编码标准(如 CODING_STANDARDS.md、CONTRIBUTING.md),并叠加一组固定的 Fowler 代码坏味道基线(神秘命名、重复代码、依恋情结、数据泥团、基本类型偏执、重复 switch、霰弹式修改、发散式变化、夸夸其谈通用性、消息链、中间人、被拒绝的遗赠)。仓库文档标准优先于基线;基线项一律视为判断性提示而非硬性违规;工具已强制的内容跳过。
- 规格轴:核对代码是否忠实实现来源 issue/PRD/spec,报告缺失或部分实现的需求、未被要求的行为(范围蔓延)、以及看似实现但实现有误的需求。
使用方式:先固定基准点,记录 git diff <fixed-point>...HEAD(三点,与 merge-base 比较)及 git log <fixed-point>..HEAD --oneline;用 git rev-parse <fixed-point> 确认引用可解析且 diff 非空,否则在此阶段失败而非在子代理内失败。随后定位 spec 来源(commit 消息中的 issue 引用、用户传入路径、docs/、specs/、.scratch/ 下匹配分支名的 PRD/spec 文件),找不到时询问用户;若用户表示没有 spec,规格轴跳过并报告「no spec available」。再定位规范来源文件。最后用一条消息并行发起两个 general-purpose 子代理,各自输出不超过 400 词的报告,汇总时分别置于 ## Standards 与 ## Spec 标题下,不合并、不重排,末尾给出一行总结(各轴发现总数与各轴最严重问题),不跨轴选唯一赢家。
阶段末即时评审模式:固定点取阶段首个 commit 的父提交(可用 git log --oneline --grep="S{N}" 查找);规格轴以 stage-spec DoD(docs/design/stage-specs/S{N}.md)为来源,DoD 未实现即 Spec fail;规范轴同普通模式;产出为状态化报告,每条 finding 标注 open/fixed/recorded 并附证据,落盘 docs/audits/stage-review-S{N}-YYYY-MM-DD.md,open 项可入账 audit-item,阶段收口由 stage-gate 跑 DoD。
限制:需要项目提供 issue tracker 约定(如 docs/agents/issue-tracker.md),缺失时须询问用户;spec 缺失时规格轴无法执行;基线坏味道为判断性提示,仓库文档标准可覆盖;具体安装命令与收费信息暂未提供。