review-walkthrough

评审流程

像资深开发者指导同行一样评审拉取请求。讲解每一部分改动及其周边代码，直到评审者能够自行修改这些代码；让他们对每项决策作出选择，最后由评审者以自己的名义发布一条 GitHub 评审意见。代码保持作者提交时的样子：你希望做出的每项改动都写成一条评审发现。

所有内容都使用 writing-lean 编写。评审发现、总结及发布方式见 REVIEW.md；所有 GitHub 调用见 GITHUB.md。

由评审者掌控节奏。 从第 3 步开始，每一步都要等到满足其完成条件，且评审者表示继续，才能结束。回答一轮问题只代表确定了评审发现，并不代表这一步结束：要询问他们是否准备好了。

1. 锁定拉取请求

参数是拉取请求编号或 URL。必须提供拉取请求，因为流程会读取其关联的问题、描述、检查结果和先前的评审记录。若未提供，则停止并建议使用 open-pr。

记录其编号、仓库、基准分支、头部 SHA、作者，以及它关闭的问题。检查是否由 Agent 编写：分支以 copilot/ 开头、作者是机器人，或提交中有 Agent 共同作者。

若评审者以前评审过此拉取请求，则这是一次后续评审：记录其上次评审所涵盖的提交（见 GITHUB.md）。待评审差异从该提交开始，一直到头部提交；若没有上次评审提交，则从基准分支开始。

完成条件：以上各项均已记录，并且已确定待评审差异。

2. 启动后台工作

将以下任务分派给后台子 Agent，让它们在评审者回答第 3 步问题时并行运行：

• code-review：检查待评审差异。其要求包括关联的问题及其 Agent 说明；若是后续评审，还包括先前评审的发现。按文档所述，将 house-rules 和 writing-lean 加入其 Standards sources 作为文档化标准；这些标准优先于其代码异味基线。若未安装 code-review，子 Agent 则改为逐项对照关联问题和 Agent 说明中的每条验收标准，检查待评审差异，并报告每项是否已满足、部分满足或缺失。
• **检查结果。**读取拉取请求的检查结果。照原样引用通过的检查。仅在本地运行失败的检查，以及 CI 未运行但文档中列出的检查；使用仓库 AGENTS.md 中的命令。
• **先前讨论串。**获取所有评审者的每条评审讨论串，并阅读每条回复。根据后续提交，对每条未解决的讨论串分类：已处理（注明对应提交）、部分处理、未处理或已不再适用。对每条已解决的讨论串，注明是否有回复确认修复。

完成条件：三项任务均已启动。

3. 了解评审者

通过 gh 和 git 确认当前使用此技能的人，然后在一轮问答中确认：

• 他们对该代码库有多熟悉；
• 评审目的是什么：通用、正确性、安全性、性能，还是了解该领域；
• 他们是否是此拉取请求的作者。

若评审者是作者，现在就告诉他们这会如何限制评审的事件；参见 REVIEW.md。

若待评审差异超过约 400 行改动，或涉及许多文件，建议先拆分拉取请求再继续。若是后续评审，则建议继续进行：用于回应评审意见的提交通常很难拆分。

他们的回答将决定每一步讲解的深度，以及评审发现的优先级：安全评审会优先指出信息泄露。

完成条件：评审者已回答问题，并已决定是否按你的建议拆分。

4. 制定步骤计划

等待 code-review 的审查发现和之前的讨论串，然后根据它们以及正在审查的差异构建步骤计划。如果 code-review 和某个讨论串对先前发现有不同意见，以讨论串中的回复为准：它们记录了审查者之后作出的决定。计划从共用基础（辅助函数、契约、数据形状）延伸到边缘和接口排序，确保每一步都建立在上一步的基础上。对包含严重发现的步骤投入最多时间，并将问题较少的部分并入相邻步骤。

将计划列为编号清单，每一步占一行并列出涉及的文件，然后让审查者重新排序、合并或跳过步骤。接着添加收尾步骤：剩余的规格、本地测试，以及起草并发布。

完成条件：审查者接受计划，且正在审查的差异中的每个文件都列在某个步骤中，或列入未审查清单。

5. 逐步审查

按以下顺序讲解每一步：

1. 目的：说明这段代码为何存在，以及它解决了什么问题。
2. 工作原理：展示代码本身，而不只是链接。用围栏代码块逐字引用每个讨论的代码块，在标题下方或链接到对应的具体行，并在发现或要点涉及的行上标注 // ←；只有样板代码可以精简，并说明已精简。仅提供链接不便于跟进。提供足够的周边系统信息，让审查者之后能够修改这段代码。
3. 重要事项：说明风险、陷阱，以及拉取请求之前就存在的问题。
4. 覆盖情况：说明哪些规格会测试这段代码，以及具体有哪些空白。
5. 本地试用：提供一种简短的方法来查看其运行效果。如果这一步会改变用户可见的内容，除非运行应用的成本较高，且请求的更改也会影响同一路径，否则现在就和审查者一起试用；若符合这两个条件，则建议延后。其他所有事项都加入草稿中的本地测试清单。

在覆盖对应代码的步骤中提出每个先前的讨论串。说明它何时已解决；若尚未解决，则建议保留该问题（参见 REVIEW.md），并让审查者决定它是否仍适用。

以一轮讨论结束每个步骤：列出每个拟议的发现，编号与 REVIEW.md 中一致；每项都要给出你的建议，并采用回答“是”即表示接受该建议的措辞。然后询问“有问题吗？或者准备好进入下一步了吗？”

❓ **F3** - **<finding title>**: <the problem, and why it matters>

➡️ <your recommended fix, and its label and blocking status>

每当某项发现达成一致，立即将其加入草稿。

完成条件：审查者的问题都已回答，且每项发现都已达成一致或被驳回。

6. 剩余规格

覆盖没有在任何步骤中讨论的规格文件，以及跨步骤的空白，例如只会在重新连接或失败时运行的路径。以一轮讨论结束。

完成条件：正在审查的差异中的每个规格文件都已讨论，且每项发现都已达成一致或被驳回。

7. 本地测试

展示本地测试清单，并询问是否现在和审查者一起运行，或等请求的更改合入后再运行。

完成条件：审查者已运行清单，或选择延后。

8. 起草并发布

按照 REVIEW.md 起草摘要和评论，建议一个事件，并发布审查。

完成条件：审查已发布，或留待审查者提交，并向审查者显示其 URL。

9. 回顾

在聊天中逐行回顾本次会话讲解的代码库概念，让审查者对该领域有个整体认识。对于已解决但仍未处理的每个先前讨论串，询问是否要回复“已在 <sha> 中解决”，并解决该讨论串；每项都要向审查者确认。

完成条件：审查者已收到回顾，并回答了任何相关询问。