pr-review-guide

在 GitHub 拉取请求上发表评论时加载此技能。

跟踪行号

分析 PR 差异时，始终随时记录每项发现的确切文件路径和行号。每项发现都必须包含发布审查评论所需的、新文件（差异右侧）中的准确 path 和 line（多行范围还需包含 start_line）。不要将行号解析推迟到后续步骤。

如果审查由子 Agent 执行，Agent 返回的每项发现都必须包含以下字段，以便调用方立即发表评论：

• path：相对于仓库根目录的文件路径
• line：新文件中的行号（多行评论的结束行）
• start_line（可选）：多行评论的起始行
• body：可直接发布的评论文本

发布审查评论

收到审查拉取请求的请求时，你可以使用 GitHub CLI 工具在 PR 上针对你发现的每个问题发布内联评论。你可以在评论中建议具体的代码更改。始终在评论中引用具体代码行，以便清晰说明。

在拉取请求上提供反馈时：

• 始终着眼于可执行的建议，帮助改进代码
• 始终确保评论清晰、简洁；提供具体示例或代码引用来支持反馈。避免含糊其辞，改为提出具体的改进建议。
• 始终针对具体代码行发表评论，绝不要只发布一条笼统的评论

建议的编辑

当问题的修复方法明确且范围较小（例如拼写错误、缺少注解、类型错误或简单重命名）时，请在审查评论中加入 GitHub 建议的编辑代码块，以便作者一键应用。使用以下格式：

```suggestion
corrected line(s) of code here
```

建议编辑的指南：

• 适用场景：拼写错误、缺少 override/[[nodiscard]]/constexpr、类型错误、简单重命名，以及正确代码明确的小型错误修复。
• 不适用场景：大型重构、设计变更、存在多种有效修复方案的情况，或需要作者根据上下文自行判断的情况。
• 建议内容应尽量精简——只修改需要修复的行。不要重新格式化周围代码。
• 如果建议跨越多行，请在代码块中包含所有受影响的行。

未解决的审查评论

审查 PR 时，始终检查之前所有审查者的评论（无论审查者是谁），包括已标记为已解决的评论。如果当前代码仍存在已解决评论中描述的问题，请将其列为一项发现，并引用原始评论。使用以下格式：

• [HIGH] 先前指出的问题仍未解决：{原始评论摘要}
  • 位置：文件和行号引用
  • 问题：{作者} 的审查评论已标记为已解决，但当前代码中仍存在该问题。
  • 证据：链接至或引用原始评论，并展示当前仍存在问题的代码。
  • 建议：合并前解决原始反馈中指出的问题。

不要将已通过其他方式妥善解决的问题列为发现，即使解决方式与审查者建议的不同。

语气

• 不要发表主观评价。 不要赞扬或吹捧处理方式，不要使用“修得不错！”或“解决方案很扎实！”之类的填充语。审查正文和内联评论中只能包含发现、问题和可执行的反馈。让发现本身说明问题。
• 审查正文应简要概述发现（可使用项目符号列表），并附上 AI 生成内容免责声明。除此之外不要写其他内容。

礼仪

• 不要在拉取请求中发布过多评论。应聚焦于最重要的问题，并明确说明如何解决。如果有轻微的风格问题，可以提及，但应优先关注更重要的架构、性能、安全或正确性问题。
• 不要修改其他审查者已有的评论或反馈。问题得到处理并解决后，可以通过新评论确认更改，但应避免编辑或删除之前的评论，以保留清晰的审查历史。
• 始终保持尊重并提供建设性意见。务必说明代码审查评论由 AI 助手撰写，可能并不完美。

CI 状态解读

审查 PR 时，请留意某些贡献者的 CI 作业可能会按预期失败：

• internal-build：需要 Cloudflare 内部访问权限。外部贡献者始终会遇到失败——这并不意味着构建或代码存在问题。对于外部贡献者提交的 PR，不要将此作业的 CI 失败标记为问题。

在将 CI 失败归因于代码问题之前，请确认 PR 作者是否为外部贡献者（即不是 Cloudflare 组织成员）。如果是，请检查失败的作业是否受访问权限限制。

工具

与 GitHub 交互时，请酌情使用 GitHub CLI（gh）工具或 git。