两轴代码审查

审查 HEAD 与用户指定的固定点之间的 diff,沿两条轴:

• Standards(标准):代码是否遵守本仓库已写明的编码标准?
• Spec(规格):代码是否忠实实现了任务来源(任务文档/工单)?

两轴作为并行子代理运行,互不污染上下文,本 skill 汇总各自发现。

流程

1. 锁定固定点

用户说的就是固定点(commit SHA、分支名、tag、main、HEAD~5 等);没说就问。

一次性取好 diff 命令:git diff <fixed-point>...HEAD(三点,与 merge-base 比较)。同时取提交列表:git log <fixed-point>..HEAD --oneline。

继续之前确认固定点可解析(git rev-parse <fixed-point>)且 diff 非空。坏的引用或空 diff 在这里失败,而不是在两个并行子代理里。

2. 定位规格来源

按顺序找任务来源:

1. 用户作为参数传入的路径(工单文件、任务文档);
2. .agentdocs/workflow/ 下与分支名或特性匹配的任务文档或工单(task.md、tickets/*.md);工单通常即规格——验收标准逐条对照;
3. 都没找到时问用户规格在哪;没有规格则 Spec 子代理跳过,报告"无可用规格"。

3. 定位标准来源

仓库里任何写明代码该怎么写的东西:CODING_STANDARDS.md、CONTRIBUTING.md、.agentdocs/ 下的领域文档中的编码约束。

在仓库标准之上,Standards 轴始终携带下方的气味基线:固定的 Fowler 代码气味清单(《重构》第 3 章),仓库什么都没写时它也生效。两条约束:

• 仓库标准优先。仓库写明的标准永远赢;它背书的东西若会被基线标记,压制该气味;
• 永远是判断题。每个气味都是带标签的启发("疑似特性依恋"),不是硬违规。工具已强制的跳过。

每个气味读作是什么 → 怎么修;对照 diff 匹配:

• 神秘命名:函数、变量、类型的名字不透露它做什么、装什么。→ 改名;起不出诚实的名字,说明设计浑浊;
• 重复代码:同一逻辑形状出现在本次改动的多个 hunk 或文件。→ 提取共享形状,两处调用;
• 特性依恋:方法伸手进别的对象的数据多过自己的。→ 把方法搬到它依恋的数据上;
• 数据泥团:同几个字段/参数总是结伴出现(一个想出生的类型)。→ 捆成一个类型,传它;
• 基本类型偏执:基本类型或字符串顶替了值得拥有自己类型的领域概念。→ 给概念建自己的小类型;
• 重复 switch:对同一类型的同一 switch/if 级联在改动中反复出现。→ 多态替换,或一张两处共享的映射;
• 霰弹式修改:一个逻辑变更迫使 diff 里散落多文件的零碎编辑。→ 把一起变的聚进一个模块;
• 发散式变化:一个文件/模块因多个不相关的原因被编辑。→ 拆分,让每个模块只因一个原因变;
• 投机泛化:为规格没有的需求加的抽象、参数、钩子。→ 删掉;内联回去,直到真实需求出现;
• 消息链:长长的 a.b().c().d() 导航,调用方不该依赖它。→ 在第一个对象上用一个方法藏起这段行走;
• 中间人:一个类或函数主要工作就是往下转发。→ 去掉,直接调真正的目标;
• 拒绝继承:子类或实现者忽略/覆盖了继承的大部分。→ 放弃继承,用组合。

4. 并行生成两个子代理

Standards 子代理的提示词包含:

• 完整 diff 命令与提交列表;
• 第 3 步找到的标准来源文件列表,外加气味基线全文粘贴(子代理没有别的途径拿到它);
• 任务书:"按文件/hunk 汇报:(a) diff 违反已写明标准的每一处:引用标准(文件与规则);(b) 发现的基线气味:命名并引用 hunk。区分硬违规与判断题:已写明标准的违反可以是硬的,基线气味永远是判断题,且仓库标准覆盖基线。工具已强制的跳过。400 字以内。"

Spec 子代理的提示词包含:

• diff 命令与提交列表;
• 规格文件的路径或内容;
• 任务书:"汇报:(a) 规格要求了但缺失或不完整的;(b) diff 里没被要求的行为(范围蔓延);(c) 看起来实现了但实现方式可疑的要求。每个发现引用规格原句。400 字以内。"

规格缺失时跳过 Spec 子代理,在最终报告注明。

5. 汇总

两份报告分别放在 ## Standards 与 ## Spec 标题下,原文或轻整理。不合并、不重排:两轴分开正是设计——合并会让一轴掩盖另一轴。

结尾一行总结:每轴的发现总数与各自轴内最严重的问题(若有)。不跨轴选冠军:那是分离要防的重排。

为什么两轴

一个变更可能过一轴、挂另一轴:

• 代码处处合规,却实现了错误的东西 → Standards 过,Spec 挂;
• 代码分毫不差做了规格的事,却破坏项目约定 → Spec 过,Standards 挂。

分开报告,一轴就掩盖不了另一轴。