SuperAPI AI 工具集

start-pr-review

编程与开发

查看项目

更新于 10-29 14:22

技能介绍

用途 该技能用于开启一次拉取请求(PR)审查会话。使用场景是:变更由他人编写,用户即将与 AI 一起对它作出判断。AI 的定位是审查者,负责发现问题、引用依据并给出建议;用户决定哪些问题构成阻塞,作者从中了解原因。会话中发现的一切以及会话期间发生的改动,都记录在作者会读到的位置——即 PR 本身,以便结束时依据记录而非记忆撰写总结。

开始前的准备 在阅读 diff 之前,先询问变更所依据的规格文档,例如 PLAN.final.md、TECHNICAL.final.md、issue 或某次对话,并阅读它。若不存在规格,需要明确说明:此时审查仅以 PR 描述为依据,“是否做到了要求之事”这个问题会变弱,用户应在收到发现之前知晓这一点。 随后阅读项目声明的原则与最佳实践,包括 PRINCIPLES.md(常见位置是 docs/PRINCIPLES.md)、AGENTS.md、CONTRIBUTING.md、PR 所触及代码区域的相关文档,以及 docs/acceptances/ATTENTION.md(如项目存在)。这些是审查标准:每条发现都引用其中之一、规格或代码。 再浏览 PR 本身:描述、git log --oneline <main>..<branch>、git diff --stat <main>...<branch>,以及分支是否落后于主集成分支。提交信息应让每项改动的意图清晰;若做不到,这本身就是一条发现。

审查方法 阅读重要的代码块,然后对整个变更及每个部分提出三个问题:

  1. 是否做到了规格所述——不多不少?未经决定而扩大的范围、缺失的需求,都是发现。作者悄悄做出的产品决策应交给用户判断,而非由审查者放行。
  2. 是否存在不必要的复杂度?例如与既有机制并行的新机制、重复实现、泛化容器、只有一个调用者的抽象、无人要求的配置、在代码已有能力时引入的依赖。简单优先于复杂,复杂度需自证其必要性。
  3. 是否有异味?例如因增长而非拆分导致的长函数和大文件、重复状态、混合关注点、描述机制而非意图的命名、被吞掉的错误、死代码,以及经典缺陷源:时间戳比较、在人机交互线程上做阻塞 I/O、基于字节的文本处理、未本地化的字符串。还要看测试是否与变更规模相称,或是否缺失。

报告与决策 先按严重程度排序报告发现,每条包含文件与行号、引用依据以及建议。由用户逐条决定哪些构成阻塞、哪些转为后续工作、哪些驳回。每个问题一次决定,用平实语言表达,先给出建议。在此对话之前不要修复任何东西:改写变更的审查者已经不再是在审查。

记录与修改 记录载体是 PR。能发布时,将每条已定论的发现作为对应行的审查评论发布,附上决定(可用 gh 或项目等效工具)。若无法从此处发布,则把同样的记录整理成一条用户可发布的消息,并说明这一点。 当用户要求修复某条发现时,通过 fix-bug 执行,作为 PR 分支上的独立提交,提交信息说明原因,并通过 commit-changes 完成。绝不要改写或强推覆盖作者的提交,未经要求不要推送。作者必须能逐条提交地读到其工作中改了什么、为什么改。

结束 当所有阻塞性发现都已修复或被有意识地接受后,使用 start-acceptance 开始验收测试:PR 分支即功能,规格即范围。审查在有人实际试用变更之前不算结束;会话以 end-pr-review 收尾。