SuperAPI AI 工具集

code-review

编程与开发

查看项目

更新于 11-04 04:19

技能介绍

用途

code-review 用于审查 HEAD 与用户指定固定点之间的代码变更(diff),从两个维度分别评估:

  • 标准(Standards):代码是否遵循本仓库中记录的编码规范。
  • 规格(Spec):代码是否忠实实现了对应的原始 issue / 规格说明。

两个轴作为并行子代理运行,避免相互污染上下文,最后由本技能汇总结果。使用前提是已向技能提供 issue 跟踪信息。

主要能力

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. 提交信息中的 issue 引用(#123、Closes #45、GitLab !67 等),通过 docs/agents/issue-tracker.md 中的工作流获取。规格即该 issue 的实现契约;当跟踪器文档说明哪个评论或正文承载该契约时,按该内容审查,其余作为上下文。
  2. 用户作为参数传入的路径。
  3. docs/、specs/ 或 .scratch/ 下与分支名或功能匹配的规格文件。

若均未找到,询问用户规格在哪里;若用户表示没有规格,则 Spec 子代理跳过并报告“无可用规格”。

3. 识别标准来源

查找仓库中说明代码应如何编写的文档,例如 CODING_STANDARDS.md、CONTRIBUTING.md。在此之上,Standards 轴始终携带以下坏味道基线(Fowler《重构》第 3 章的固定代码坏味道集合),即使仓库未记录任何规范也适用。两条约束:仓库规范优先,已记录的仓库标准总是胜出,若其认可基线会标记的内容则抑制该坏味道;一切均为判断性提示,每个坏味道都是带标签的启发式(如“可能的 Feature Envy”),绝非硬性违规,且跳过工具已强制检查的内容。

每个坏味道按“是什么 → 如何修复”匹配 diff:

  • Mysterious Name:函数、变量或类型名称无法揭示其作用或内容 → 重命名;若找不到诚实的名字,说明设计本身模糊。
  • Duplicated Code:同一逻辑形态在变更中的多个 hunk 或文件出现 → 提取共享形态,两处调用。
  • Feature Envy:方法访问另一对象的数据多于自身 → 将方法移到它所依恋的数据上。
  • Data Clumps:同一组字段或参数总是结伴出现(一个想诞生的类型)→ 打包成一个类型传递。
  • Primitive Obsession:用原始类型或字符串代替值得独立类型的领域概念 → 为该概念建立小类型。
  • Repeated Switches:对同一类型的相同 switch/if 级联在变更中反复出现 → 改为多态,或两处共享一个映射。
  • Shotgun Surgery:一次逻辑变更迫使 diff 中多个文件分散修改 → 将一起变化的内容聚集到一个模块。
  • Divergent Change:一个文件或模块因多个不相关原因被修改 → 拆分,使每个模块只因一个原因变化。
  • Speculative Generality:为规格中不存在的需求添加抽象、参数或钩子 → 删除,内联回去直到出现真实需求。
  • Message Chains:调用方不应依赖的长链 a.b().c().d() 导航 → 在第一个对象上用单个方法隐藏该链路。
  • Middle Man:主要只是向下委托的类或函数 → 移除,直接调用真实目标。
  • Refused Bequest:子类或实现者忽略或覆盖了大部分继承内容 → 放弃继承,改用组合。

4. 并行启动两个子代理

Standards 子代理的提示包括:完整 diff 命令与提交列表;步骤 3 找到的标准来源文件列表,加上完整粘贴的坏味道基线(子代理无其他途径获取);简报:“按文件/hunk 报告:(a) diff 违反已记录标准的每一处:引用标准(文件 + 规则);(b) 发现的任何基线坏味道:命名并引用该 hunk。区分硬性违规与判断性提示:已记录标准的违反可为硬性,但基线坏味道始终是判断性提示,且已记录的仓库标准覆盖基线。跳过工具检查的内容。400 词以内。”

Spec 子代理的提示包括:diff 命令与提交列表;规格的路径或已获取内容;简报:“报告:(a) 规格要求但缺失或不完整的需求;(b) diff 中未被要求的改动(范围蔓延);(c) 看似已实现但实现有误的需求。每条发现引用规格原文。400 词以内。”若规格缺失,跳过 Spec 子代理并在最终报告中注明。

5. 汇总

在 ## Standards 与 ## Spec 标题下分别呈现两份报告(逐字或轻度清理)。不要合并或重新排序发现,因为两个轴是刻意分开的。最后一行总结:每轴发现总数,以及各轴内最严重的问题(若有)。不要在轴之间选出唯一赢家,那正是分离双轴所避免的重新排序。

为什么两个轴

变更可能通过一个轴而失败于另一个轴:

  • 遵循所有标准但实现了错误的东西 → 标准通过,规格失败。
  • 完全按 issue 要求实现但违反项目约定 → 规格通过,标准失败。

分开报告可防止一个轴掩盖另一个轴。

读取文件

路径相对于仓库根目录:

  • docs/agents/issue-tracker.md:如何获取提交信息引用的 issue,以及哪个评论或正文承载 issue 的实现契约。缺失且未提供跟踪器时,按步骤 2 的其他位置查找规格,不阻塞审查。
  • docs/、specs/ 或 .scratch/ 下的规格文件。缺失时按步骤 2 询问用户规格在哪里。
  • CODING_STANDARDS.md、CONTRIBUTING.md 以及仓库中记录代码编写方式的其他内容。缺失时,Standards 轴仅携带坏味道基线。

适用场景与限制

适用于以固定点为基准、同时关心“合规”与“符合规格”的代码变更审查,尤其适合有 issue 跟踪与编码规范文档的仓库。限制:需要用户提供固定点,未提供需询问;需要规格来源,找不到需询问或由 Spec 轴跳过并注明;基线坏味道均为判断性提示而非硬性违规;不处理工具已强制检查的内容;不跨轴挑选单一最严重问题。