start-pr-review

开始审查拉取请求

这项改动由其他人编写，用户即将与你一起评判它。 你担任审查者：找出问题、引用依据并提出建议；用户决定 哪些问题会阻止合并，作者则了解原因。你发现的所有问题以及 会话期间发生的所有变更，都会记录在作者能看到的地方—— PR 中——这样 end-pr-review 就能根据 记录而不是记忆来总结并结束会话。

阅读差异之前

1. 询问规格说明。 审查要依据改动原本应该实现的目标。询问它是根据哪份文档编写的——PLAN.final.md、TECHNICAL.final.md、议题、对话——然后阅读该文档。如果没有，请说明这一点：此时审查只能依据 PR 描述，这会让“是否实现了要求”成为一个较弱的问题，用户应在看到审查结果前知晓这一点。
2. 阅读项目声明的原则和最佳实践——PRINCIPLES.md（通常位于 docs/PRINCIPLES.md）、AGENTS.md、CONTRIBUTING.md、PR 所涉及代码区域的文档——以及项目有提供时的 docs/acceptances/ATTENTION.md。它们是审查标准：每条审查意见都要引用其中一项、规格说明或代码。
3. 了解 PR 全貌：其描述、git log --oneline <main>..<branch>、git diff --stat <main>...<branch>，以及分支是否落后于主集成分支。提交消息应清楚说明每项改动的意图；如果没有做到，这本身就是一条审查意见。

审查

阅读重要的代码块，然后针对整体和每个部分提出三个问题：

• 它是否恰好实现了规格说明中的要求？ 未经决策就扩大的范围，以及缺失的要求，都是审查意见。作者悄然做出的产品决策应交由用户决定，审查者不应擅自放行。
• 其中是否存在不必要的复杂性？ 在现有机制旁再建一套机制、重复复制内容、使用通用容器、只有一个调用方的抽象、无人要求的配置，或者代码已有相应能力却引入依赖。规则是简单胜于复杂；应由复杂性本身证明其合理性。
• 其中是否存在可疑之处？ 不断增长而未拆分的冗长函数和大型文件；重复状态；职责混杂；描述实现机制而非意图的名称；被吞掉的错误；死代码；以及合并分支列表中的典型错误来源——时间戳比较、在响应用户请求的线程上执行阻塞 I/O、按字节处理文本、未本地化的字符串。测试是否与改动相称，或者是否缺少测试。

先报告审查意见，按严重程度排序，每条都注明文件和行号、引用依据以及建议。由用户决定哪些问题会阻止合并、哪些作为后续工作，以及哪些不予采纳——每个问题只做一个决定，使用直白的措辞，并优先给出你的建议。在完成这番讨论前，绝不要修复任何内容：审查者一旦改写改动，就不再是在审查了。

记录与变更

• PR 就是记录。 尽可能将每条已定案的审查意见作为审查评论发布在相关代码行上，并注明决定（使用 gh 或项目的同等工具）。如果无法从此处发布，就将同样的记录整理成一条用户可以发布的消息，并说明这一点。
• 用户要求你修复某条审查意见时，使用 fix-bug 进行修复，并通过 commit-changes 将其作为 PR 分支上的独立提交，提交消息要说明原因。绝不要重写作者的提交或强制推送覆盖它们；除非用户要求，否则不要推送。作者必须能够逐个提交地了解其工作改了什么以及为什么改。

确认所有发现后

修复或明确接受所有阻塞性发现后，使用 start-acceptance 开始验收测试：PR 的分支是功能，规范是范围。只有在有人实际试用过这项变更后，评审才算结束；会话以 end-pr-review 结束。