code-review

代码审查

每当你审查代码变更时，都要使用此能力——无论是拉取请求、分支或提交范围的差异，还是你在宣布自己的工作完成前进行的自审查，也无论变更类型、语言或领域是什么。此技能是自包含的：所需的每条规则都包含在此处，因此即使单独安装、没有任何配套技能，也能保持有效。如果宿主项目有自己的代码审查指南或已发布的审查政策，应遵循其中针对项目的规则和优先级；只要项目指南未作规定，此处的方法仍应完整适用。

审查只有一个任务——判断变更是否可以安全合并，并以证据说明原因——也只有一种输出：报告。审查不会重写代码。发现问题和修复问题应分开处理。

**审查目标。**目标是当前正在审查的变更：默认情况下，是工作树相对于基分支的差异；也可以是指定的拉取请求引用、分支名称或提交范围。阅读其他内容之前，先确定该目标的差异（参见 scoping.md）。

本文档中的关键词 “MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“MAY” 和 “OPTIONAL”，应按照 RFC 2119 中的描述进行解释。

审查流程

每次审查都遵循相同的流程：重置到审查者模式，根据差异确定变更范围，通过审查视角评估该差异，按严重程度分类每项发现，提供有证据支持的报告，并将风险过高、无法自行批准的事项升级处理。重置步骤是其余流程可信的基础——审查者应像检查他人编写的代码那样，检查代码_实际做了什么_，而不是再次肯定产生代码的推理过程；在作者和审查者是同一个 Agent 的自审查中，这一点尤为重要。重置之前不要阅读任何代码——这是规范流程的第一步，由 scoping.md 负责说明。以下各节按审查流程中的步骤顺序，指向负责说明各步骤的参考文档。

指南：

• 在评估变更之前，MUST 阅读 review-lenses.md；其中的验收标准边界和限定范围的重构检查适用于每次审查。

审查范围界定

参见 scoping.md，了解如何：

• 执行审查者模式重置，并通过 git status / git diff / PR 差异确定审查范围
• 区分范围内的代码（差异）和范围外的代码（预先存在的代码）
• 阅读完整文件，以及变更代码块周围的所有调用方和被调用方
• 根据相邻代码实际声明的内容，而不只是根据差异，核验变更对边界的说明——即变更所指明的负责方
• 处理未跟踪文件、空差异或含糊不清的差异，以及生成文件 / 工具管理的文件

严重程度分类

参见 severity.md，了解：

• Critical / Major / Minor / Nit 的定义，以及各级别与合并影响和缺陷类别的对应关系
• 针对已提交的密钥、缺少访问控制、未经清理的输入，以及引入的测试或 lint 失败等类别所规定的最低严重程度
• 如何根据各严重程度的问题数量，将结论映射为 Approve / Approve with Nits / Request Changes
• 如何通过向上升级并说明假设来处理不确定的严重程度

标记内容：审查视角

请参阅 review-lenses.md，了解：

• 正确性视角：逻辑错误、边缘情况、错误和异步处理、契约变更
• 基于代码检查而非外部验证限制的验收标准问题
• 检查变更代码中的具体重构机会，不进行推测性或无关的清理
• 可维护性视角：命名、组织、抽象边界、复杂度、死代码、范围控制，以及为内容添加类变更明确应删减的内容
• 安全与隐私视角：机密、输入验证、访问控制、注入、SSRF、身份验证、数据泄露、供应链
• 测试与验证视角：覆盖率、稳定的测试钩子、快照、脆弱性、手动检查
• 性能与可靠性视角：数据访问成本、并发、缓存、资源和包体积、故障模式

证据与报告

请参阅 evidence-and-reporting.md，了解：

• 每条问题都必须附带 file:line 引用，并引用有问题的代码
• 每条 Critical 和 Major 问题都必须提供 diff 风格（-/+）的修复片段
• 审查报告从 Summary 到 Recommended Actions 的确切章节顺序
• 哪些内容算作证据而非断言，以及如何标记审查者无法验证的问题
• 作者对变更的描述——验证表、作者编写的验收标准、披露的数据——能证明什么，不能证明什么

审查语气

请参阅 tone.md，了解：

• 针对代码而非作者进行反馈，并说明每条问题背后的具体风险
• 如实肯定实际优点，不夸大细枝末节；这是内部审查报告必须做到的，但已发布审查的摘要无此要求
• 不要将风格和偏好列为阻塞性严重级别的问题
• 明确标出假设，并将人工撰写的文案留给其作者处理

升级处理与决策

请参阅 escalation.md，了解：

• 只报告审查结果——不修改代码，也不将审查工作委派出去
• 让每项修复都易于直接应用，并配套相应的验证步骤
• 高风险变更应升级至外部关卡，而非自行批准
• 将真正的权衡作为逐项列出的“需要决策”事项交由调用方决定

已发布的审查与 CI 审查

请参阅 posted-review-policy.md，了解：

• 何时将审查发布到拉取请求（由 CI 审查者或托管审查产品执行），而非仅作为内部自我审查
• 采用项目明确采纳的原生呈现方式和报告范围，而非与之冲突的作者报告默认规则，同时保留实质性检查和原始问题
• 将内部四级分流归并为默认的两种标签 Important / Nit 报告，并附上一行统计
• 运行仓库要求的检查，并遵守其禁止报告的排除项；这些排除项应以清单形式列出，每项检查的范围应与其屏蔽的问题完全一致，绝不使用笼统的“CI 强制执行的任何内容”条款
• 在阅读 diff 之前，选择默认的作者报告，并通过平台支持 diff 锚定评论的审查机制一次性提交；对于建议性审查者，结论应不具阻塞性
• 将默认摘要限定为三项白名单——统计、无法检查的内容，以及没有行号可供锚定的问题；唯一例外是主机要求逐轮列出内容