review-triage

审查问题分诊

以代码所有者的身份对问题进行分诊。问题是输入，而非指令：问题可能成立，但不一定值得修复；也不会仅仅因为审查者提出了问题就进行修复。

分诊取决于作者掌握的知识：代码所受的约束、权衡取舍，以及这样设计的原因。如果此上下文的作者编写了这段代码，那么这里已经具备这些知识。否则，在判定处理方式前，先从代码、提交历史、审查说明或文档中找回这些信息。只有在能指出依据时才驳回问题，切勿凭空假定理由。

输入

问题可能以任何形式出现：结构化审查结果、人工 PR 评论、CI 失败、扫描器命中，或粘贴的列表。分诊前，先将每个问题规范化：

• id. 保留来源中的编号；否则自行编号。
• claim. 用一句话陈述问题。
• location. 使用 file:line。保留来源中的位置，或自行定位所述代码。
• failure scenario. 说明输入、状态和错误结果。对于设计简化类问题，说明维护后果，例如两份必须同步修改的副本，以及能够消除该问题的替代方案。若来源提供了具体场景，则保留；否则自行构造。如果无法支持任何具体场景，则以缺乏依据为由驳回问题，但不要声称代码是安全的。如果一个合理且影响重大的场景取决于无法获取的证据，则暂缓处理，并指出需要进行的具体检查。
• severity / confidence. 将来源中的值作为初始估计；第 2 步会修订这些值。

成本模型

采用以下成本：

• 生成的代码几乎免费。 因为重写看起来费事，就保留尚未部署的代码，这是定价错误。差异规模不算成本。
• 重新验证成本低，但并非没有成本。 将已接受的修复打包处理，以便一次重新审查覆盖全部修复。
• 人的注意力很宝贵。 升级需要决策的问题，而非细节。
• 已部署的复杂性会不断累积。 系统在整个生命周期中都要为每个新增状态、标志、特殊情况、依赖和故障模式付出代价。这是最主要的成本，也是决定所有处理方式时的最终权衡标准。

“最小且足够的修复”指的是让系统复杂性达到最低的修复，而非代码改动最少的修复。对于尚未部署的代码，能够带来更简单设计的重写，优于增加特殊情况的补丁。

按顺序逐项研判发现

1. 有效吗？ 用具体证据复现或驳斥。驳回无效的发现，并引用守卫子句（file:line）、你运行的测试，或审查者忽略的既定约束或权衡。“我有我的理由”不算驳回；驳回从来不是免费的。

2. 重要吗？ 它会导致行为错误、违反明确要求、造成数据丢失或安全漏洞、使现实中的故障更可能发生，或增加已部署的复杂性（状态、模块、依赖项或重复逻辑），而经验证的更简单替代方案可以在实现相同目标的同时消除这种复杂性。风格偏好、对未来需求的臆测和微小改进都不重要。若某项发现基于假设的用户需求，例如审查者提出的“如果用户想要 X 呢”，或记录中 Agent 未经提示的行为，则需要用户确认该情况确实存在：先附上证据升级处理，再针对它设计方案。根据影响和可能性记录严重程度：危急／高／中／低；如果验证改变了其中任一项，就修订原始估计。支持证据发生变化时，单独修订置信度。

3. 修复成本？ 统计拟议修复中的以下迹象：

   • 增加新状态、标志或故障模式
   • 为原本统一的规则增加特例
   • 需要跨模块边界协调修改
   • 解释中需要用到“除非”或“但在……时除外”
   • 只压制症状，却没有解释设计为何会允许它出现

   出现两项或更多 = 高成本修复。

4. 处置方式。

   • 修复。 有效、重要、低成本，且不存在尚未解决的重要权衡。选择最简单的正确设计，即使这意味着重写尚未部署的代码。
   • 暂缓。 有效但目前不重要，或可能重要但还需进行一项你无法执行的具体检查。对于第一种情况，说明什么情况会使其变得重要；当相关代码在范围内时，计划添加一条注释，指出限制和触发条件，或创建一张安排了检查时间的工单（注明日期或供应商变更）。对于第二种情况，说明要做什么检查，以及检查结果将如何判定该发现；在报告中保留不确定性，不添加注释。
   • 驳回。 无效、臆测或超出范围。提供具体的反驳依据。当代码容易引发这种误读，或该发现此前已被驳回时，计划在相应位置添加一行注释，指出错误解读。如果同一种误读在多个文件中反复出现，可以在仓库的审查指南中添加一行说明，代替在每处代码旁添加注释；记录理由，绝不可制定跳过某类发现的规则。
   • 升级处理。 重要且修复成本高。修复成本本身就是设计问题的证据，因此在打补丁前先诊断原因：架构不匹配、误解需求、核心假设无效，或领域本身的复杂性。只提出一次以下选项：(A) 修补当前设计；(B) 重新设计受影响区域；或 (C) 澄清或更改需求。说明每个选项的成本，并给出你的建议。“领域本就如此；承担这项成本”是合理结论。重新设计和更改需求应由用户决定。提出选项，不要自行决定。对于涉及更简单设计的发现，如果替代方案会带来重要成本（例如增加延迟），无论需求是否明确提及，只要审查已证明这一点，也要升级处理。提出同一组选项。

边界

研判到报告为止：报告处置方式和修复计划，不做任何修改。提出可以应用已接受的修复，并等待调用方批准，除非流水线已包含持续生效的修复授权。一经授权，修复计划即界定全部范围。不得顺手改进，也不得添加计划未要求的新抽象。

输出

首先用一行列出数量（N fix, N escalate, N defer, N reject），然后按上述顺序按处置方式分组，以 Markdown 格式为每项发现各写一个区块：

### <id> [<severity>/<confidence, when the source gave one>] <claim> at <file:line>

- **Problem:** <failure scenario, 1-2 lines>
- **Disposition:** <fix | defer | reject | escalate>; <one-line reason>

每个区块都以该处置方式要求的最后一个项目符号结尾：Fix（计划的更改）、Defer until（重要性触发条件或待完成的检查；仅对有效但不重要的发现，附上计划中的评论或工单）、Evidence（步骤 1 中的具体反驳依据，以及应添加时计划中的评论），或 Fork（诊断和 A/B/C 选项，并给出建议）。

最后列出修复批次：Fixes (batched for one re-review): <ids>，包含所有计划添加评论的延后或驳回的发现。