SuperAPI AI 工具集

code-review

编程与开发

查看项目

更新于 10-18 16:13

技能介绍

用途

code-review 用于对一段代码变更做结构化审查。它比较 HEAD 与用户提供的固定点(提交 SHA、分支名、标签、main、HEAD~5 等),沿两个独立轴给出审查结果:

  • Standards:代码是否遵循本仓库文档化的编码规范。
  • Spec:代码是否忠实实现来源 issue / PRD / 规格说明。

两个轴刻意分开报告,避免一个轴掩盖另一个轴的问题。例如代码完全合规但实现错了东西,会表现为 Standards 通过、Spec 失败;反之实现符合 issue 但破坏项目约定,则 Spec 通过、Standards 失败。

主要能力

固定点与差异捕获

以用户指定的固定点为基准,执行 git diff <fixed-point>...HEAD(三点比较,对 merge-base 做比较),并通过 git log <fixed-point>..HEAD --oneline 记录提交列表。在继续之前会先确认固定点可解析(git rev-parse <fixed-point>)且差异非空;无效引用或空差异在此阶段直接失败,而不是留到两个并行子代理内部才报错。

规格来源识别

按以下顺序查找来源规格:

  1. 用户作为参数传入的路径。
  2. .scratch/、docs/ 或 specs/ 下与分支名或功能匹配的 PRD/规格文件(本地 markdown 规格的默认位置,无需额外配置)。
  3. 提交信息中的 issue 引用(#123、Closes #45、GitLab !67 等),通过 docs/agents/issue-tracker.md 中的流程获取(仅在配置了远程跟踪器时)。

若未找到,会询问用户规格位置;若用户表示没有规格,Spec 子代理将跳过并报告“no spec available”。仅当规格位于远程跟踪器(GitHub/GitLab)时,才需要 docs/agents/issue-tracker.md,并通过 /setup-skills 配置。

规范来源与代码异味基线

Standards 轴首先读取仓库中记录编码方式的所有文档(如 CODING_STANDARDS.md、CONTRIBUTING.md)。在此基础上始终叠加一组固定的 Fowler 代码异味基线(《Refactoring》第 3 章),即使仓库没有任何文档也适用。两条规则约束该基线:

  • 仓库优先:文档化的仓库标准总是胜出;若仓库标准认可某种做法,则抑制对应异味。
  • 始终是判断性结论:每种异味都是带标签的启发式(如“可能的 Feature Envy”),绝非硬性违规;与其它标准一样,跳过工具已强制检查的内容。

基线异味包括:Mysterious Name(名称不揭示用途或内容)、Duplicated Code(相同逻辑形状出现在多处)、Feature Envy(方法过度访问他对象数据)、Data Clumps(相同字段或参数反复成组出现)、Primitive Obsession(用原始类型或字符串代替应独立建模的领域概念)、Repeated Switches(同一类型上重复出现相同 switch/if 级联)、Shotgun Surgery(一次逻辑变更导致多文件散落修改)、Divergent Change(同一文件因多个无关原因被修改)、Speculative Generality(为规格不存在的需求添加抽象、参数或钩子)、Message Chains(长链式导航 a.b().c().d())、Middle Man(类或函数主要只做转发)、Refused Bequest(子类忽略或覆盖大部分继承内容)。

并行子代理

通过单条消息发起两个 Agent 工具调用,均使用 general-purpose 子代理,并传入 model: haiku 与 effort: medium。该审查固定以 Haiku、中等推理强度运行以控制成本。

Standards 子代理的提示包含:完整的 diff 命令与提交列表;第 3 步找到的规范来源文件列表,以及完整粘贴的异味基线(子代理无法通过其它途径获取)。要求报告:每个相关文件/hunk 中(a)所有违反文档化标准之处,引用标准(文件 + 规则);(b)发现的基线异味,命名并引用该 hunk。区分硬性违规与判断性结论——文档化标准的违反可以是硬性的,但基线异味始终是判断性结论,且文档化的仓库标准优先于基线。跳过工具已强制检查的内容。控制在 400 词以内。

Spec 子代理的提示包含:diff 命令与提交列表;规格路径或获取到的内容。要求报告:(a)规格要求但缺失或部分实现的需求;(b)差异中未被要求的行为(范围蔓延);(c)看似已实现但实现有误的需求。每条发现均引用规格原文。控制在 400 词以内。若规格缺失,则跳过 Spec 子代理并在最终报告中说明。

结果汇总

在 ## Standards 与 ## Spec 标题下呈现两份报告,原文照录或轻度清理。不合并、不重排发现——两个轴刻意保持独立。最后以一行总结收尾:每个轴的发现总数,以及每个轴内最严重的问题(若有)。不在轴之间挑选单一优胜者,因为这种分离正是为了防止重排序。

使用方式

用户提供固定点(提交 SHA、分支名、标签、main、HEAD~5 等);若未指定则被询问。随后可传入规格路径;否则按上述顺序自动查找。审查完成后输出双轴报告。远程跟踪器场景需先运行 /setup-skills 配置 docs/agents/issue-tracker.md。

适用场景

  • 提交或合并前对分支差异做规范与需求实现双重检查。
  • 团队需要同时关注编码标准一致性和需求还原度。
  • 本地已有 markdown 规格(.scratch/、docs/、specs/)的项目,无需额外配置即可使用。

限制

  • 需要用户提供固定点,否则会先询问。
  • 无规格时 Spec 轴跳过并标注,不能凭空审查需求符合性。
  • 远程跟踪器(GitHub/GitLab)中的规格需要 docs/agents/issue-tracker.md 与 /setup-skills 配置。
  • 基线异味为判断性结论,非硬性违规;仓库文档化标准优先于基线。
  • 该技能固定使用 Haiku、中等推理强度运行,费用与效果以此为前提。