code-review 是对代码变更做双轴审查的技能,审查范围是 HEAD 与用户提供的固定基准点(可以是 commit SHA、分支名、标签、main、HEAD~5 等)之间的差异。如果用户没有指定基准点,技能会要求其提供。
用途
它把代码审查拆成两个互不干扰的问题:代码是否遵循本仓库文档化的编码规范(Standards 轴),以及代码是否忠实实现了来源 issue 或 spec(Spec 轴)。这样划分是因为一次变更可能通过其中一轴却无法通过另一轴:完全遵守规范但实现错了东西,或完全实现了 issue 要求却破坏了项目约定。分开报告可以防止一轴掩盖另一轴的问题。
主要能力
标准轴:先收集仓库中记录代码写法的文档,例如 CODING_STANDARDS.md、CONTRIBUTING.md。在仓库文档之外,该轴始终携带一组固定的 Fowler 代码坏味基线(出自 Refactoring 第 3 章),即使仓库什么都没规定也会套用。基线包含神秘命名、重复代码、特性依恋、数据泥团、基本类型偏执、重复分支、散弹式修改、发散式变化、夸夸其谈通用性、消息链、中间人、被拒绝的遗赠等。两条规则约束基线:仓库文档优先,若仓库标准认可某种做法,则抑制对应的坏味;所有坏味都只是带标签的启发式判断(例如“可能的特性依恋”),不是硬性违规;工具已能强制检查的内容跳过。
规范轴:按顺序寻找来源 spec:提交信息中的 issue 引用(#123、Closes #45、GitLab !67 等,通过 docs/agents/issue-tracker.md 中的流程获取);用户作为参数传入的路径;docs/、specs/ 或 .scratch/ 下与分支名或功能匹配的 spec 文件。如果都找不到,会询问用户;如果用户表示没有 spec,则跳过该轴并报告无可用 spec。
使用方式
- 固定基准点:记录一次 git diff <fixed-point>...HEAD(三点,以便与 merge-base 比较),并记录 git log <fixed-point>..HEAD --oneline 的提交列表。继续之前先确认基准点能解析(git rev-parse <fixed-point>)且 diff 非空;错误的引用或空 diff 应在此处失败,而不是在并行子代理内部失败。
- 识别 spec 来源与标准来源。
- 并行启动两个子代理:标准子代理获得 diff 命令、提交列表、标准来源文件以及完整的坏味基线文本,要求按文件或 hunk 报告文档标准违规(引用标准文件与规则)和基线坏味(命名并引用 hunk),区分硬性违规与判断性意见,跳过工具已强制检查的内容,400 词以内;规范子代理获得 diff 命令、提交列表和 spec 路径或内容,报告 spec 要求但缺失或只完成部分的需求、diff 中未被要求的行为(范围蔓延)、看似实现但实现有误的需求,每项引用 spec 原文,400 词以内。
- 汇总:在 ## Standards 与 ## Spec 标题下分别呈现两份报告,原文或轻度清理,不合并、不重排序,最后给出一行摘要,说明各轴发现总数以及各轴最严重的问题(如有),不在两轴之间选单一赢家。
适用场景
适用于需要对两次提交之间或分支相对固定点的变更做结构化审查、并同时关注“写得对不对”和“做得对不对”的仓库开发流程,尤其是已有编码规范和 issue 跟踪体系的项目。
限制
需要用户提供固定基准点;需要仓库中存在可识别的编码规范文档才能进行标准轴硬性违规判断,否则仅依据坏味基线作启发式判断;规范轴依赖 issue tracker 配置(docs/agents/issue-tracker.md,缺失时需运行 /setup-matt-pocock-skills)或用户提供 spec;spec 缺失时规范轴不执行。审查结果依赖子代理对 diff 与文档的解读,坏味发现均为判断性意见而非确定性结论。