code-reviewing

进行代码审查时，请遵循以下规则。

确定审查范围

在收集 PR 上下文之前：

• 阅读适用的 AGENTS.md 文件和链接的审查说明。
• 你必须遵循仓库的 PR 上下文说明，包括要求使用的工具和工作流。

根据用户的请求选择审查范围：

1. 未指定目标：已暂存和未暂存的差异，以及未跟踪文件及其内容。
2. 提交：提交元数据和补丁。
3. 分支或基准引用：合并基点、自该基准以来的提交，以及分支差异。如果分支已合并，则使用拉取请求元数据中的历史基准和头部。
4. 拉取请求 URL 或编号：拉取请求上下文、基准和头部提交、提交列表以及历史差异。对于已合并的拉取请求，还要包含其历史迭代或合并元数据。只有在请求或仓库提供程序能明确表明其为拉取请求时，才将单独的编号视为拉取请求。

如果无法获取所请求的目标或提供程序元数据，请报告这一情况，不要改选其他审查范围。

---

确定规范来源

规范审查对于评估正确性至关重要。

• 你必须遵循仓库的规范发现说明。
• 你必须发现并阅读所有适用的规范。不要止步于第一个来源。
• 按照相关链接查阅需求、验收标准和设计规范。

如果仓库未规定发现流程，请按以下顺序搜索所有这些来源：

1. 用户提供的路径、URL、问题或工作项 ID，或需求文本。
2. 拉取请求中链接的规范和工作项，包括其描述和讨论。
3. 提交消息中的问题引用，使用仓库配置的问题跟踪工作流。
4. 与变更代码相关的仓库本地规范和需求文档。

如果因工具不可用、权限缺失、来源无法访问或必需引用尚未解决，导致无法遵循仓库指定的发现流程：

1. 说明遇到的阻碍。
2. 你必须询问用户是否接受不完整的规范审查。
3. 等待用户明确批准后再继续。不要默默改用备用方案。

如果没有因仓库指定的发现流程受阻，则无需就缺失或未阅读的规范询问用户。

• 仅审查能够验证的内容。
• 报告缺失或未阅读的规范，即使用户已批准继续也是如此。
• 如果规范发现或阅读不完整，不要声称已全面符合规范。

---

确定标准来源

仓库中任何说明代码应如何编写的文档，例如 CODING_STANDARDS.md 或 CONTRIBUTING.md。

请纳入适用的 AGENTS.md 文件，以及收集上下文时发现的约定文件。即使仓库未记录任何标准，也要阅读代码异味基线。

---

收集上下文

仅查看差异并不足够。 获取差异后，应阅读所有被修改文件的完整内容，以了解完整上下文。孤立来看似乎有问题的代码，在周边逻辑中可能是正确的，反之亦然。

• 使用差异确定哪些文件发生了更改
• 对于工作区审查，完整阅读每个相关的未跟踪文件
• 阅读完整文件，以了解现有模式、控制流和错误处理
• 检查是否存在现有的样式指南或约定文件（CONVENTIONS.md、AGENTS.md、.editorconfig 等）

Bug

Bug——首要关注项。

• 逻辑错误、差一错误、条件判断不正确
• If-else 守卫：缺少守卫、分支不正确、无法到达的代码路径
• 边界情况：null/empty/undefined 输入、错误条件、竞态条件
• 安全问题：注入、绕过身份验证、数据泄露
• 错误处理有缺陷，导致吞掉失败、意外抛出异常，或返回未被捕获的错误类型。

性能——仅在问题明显时标记。

• 对无界数据进行 O(n²) 操作、N+1 查询、在热点路径中执行阻塞 I/O

行为变更——如果引入了行为变更，请指出（尤其是可能无意引入的变更）。

规范合规性

• 必须依据发现阶段读取的所有适用规范审查这些变更。
• 指出缺失或实现不正确的要求。
• 对每条发现，引用相关要求。

将与 Bug 无关的结构和惯例问题归入“编码规范”。

---

编码规范

依据发现的仓库规范和提供的异味基线审查差异。报告违反文档规范的问题时，注明规范所在文件及规则。对于基线异味，指出异味名称并引用相关代码块。判断有疑问的问题、仓库覆盖规则以及工具强制执行的问题，均按基线规则处理。

结构——代码是否符合代码库的结构？

• 是否遵循现有模式和惯例？
• 是否有应当使用但未使用的既有抽象？
• 是否存在可通过提前返回或提取代码来简化的过度嵌套？

在此处报告与 Bug 无关的问题，而非行为故障。说明违反之处或结构问题及其影响。

---

标记问题之前

务必确认。 如果要将某项问题认定为 Bug，就必须有把握它确实是 Bug。

• 只审查本次变更——不要审查未修改的既有代码
• 如果不确定某项是否为 Bug，就不要标记——先调查
• 不要臆造假设性问题——如果某个边界情况值得关注，请说明它会在什么现实场景下导致故障
• 如果需要更多上下文才能确认，请使用以下工具获取

不要过分纠结风格。 检查规范时：

• 确认代码确实违反规范。若已正确使用提前返回，就不要仅因存在 else 语句而提出异议。
• 某些“违规”在最简单的方案中可以接受。如果替代方案过于复杂，使用 let 语句也没问题。
• 无论其他风格选择如何，过度嵌套都是合理的关注点。
• 不要标记个人风格偏好。只报告违反既定项目惯例的问题或基线异味判断。

---

工具

使用以下工具辅助审查：

• 代码库上下文——了解现有代码如何处理类似问题。在声称某种做法不符合项目惯例之前，先检查其模式、惯例和先例。
• 库/API 上下文——使用相关的可用技能或经认可的文档，核实库/API 的用法，再指出错误。
• Web 搜索——如果不确定某种做法，请研究最佳实践。

如果你对某个问题不确定，且无法使用这些工具进行核实，请说“我不确定 X”，不要将其作为确定的问题提出。

---

输出

根据你的判断和适用的仓库文档，使用 Critical、High、Medium 或 Low 严重级别。评估严重级别，而不是判断 PR 是否应该合并或某项发现是否应阻止合并。

1. 如果存在错误，应直接、清楚地说明错误的原因。
2. 清楚传达问题的严重程度。不要夸大严重性。
3. 批评意见应明确说明触发错误所需的场景、环境或输入。评论应立即指出问题的严重程度取决于这些因素。
4. 语气应客观，不带指责，也不过度正面。内容应像有帮助的 AI 助手建议，而不要太像人类审查者的表达。
5. 让读者无需仔细阅读就能快速理解问题。
6. 避免奉承，不要提出对读者没有帮助的评论。避免使用“做得好……”或“感谢……”之类的措辞。
7. 针对每项发现，注明受影响的文件和行号。

每项发现使用三级编号标题，其中包含方括号括起的严重级别和简短、具体的标题。标题后添加包含文件和行号范围的 Location: 字段，然后说明发现的问题及其影响。编码标准相关的发现还应包含 Standard: 字段，并在适用时注明规则所在文件和行号。对于未成文的约定或结构方面的问题，应指出既有模式或说明相关问题，而不要虚构标准引用。

先在 ## Bugs 下列出发现，然后在 ## Coding standards 下列出发现。即使没有发现，也要保留这两个章节，并注明未发现问题。

每份报告都必须附加 ## Specifications reviewed，即使没有发现也不例外：

• 必须列出发现的每一项规范引用或 URL，而不能只列出在发现中引用的内容。
• 包含所有已阅读的规范。保留 URL、仓库路径以及问题或工作项 ID 的原样。
• 指明没有引用来源的用户要求来自何处。
• 将每个来源标记为已阅读或未阅读。
• 说明发现限制、阻碍因素，以及用户是否批准继续操作。
• 如果未发现任何规范，请说明这一点。