code-review

Code Review

审查的目标是判断本次变更能否安全交付，而不是逐行挑错或替作者设计产品。先恢复实际变更和它必须满足的合同，再用与风险相称的深度取得证据。

评审对象和权限

评审结论只覆盖上级提交的候选变更和已经接受的合同。Reviewer 可以阻止这个候选合入或作为该范围的阶段结果交付，但不据此宣布整个用户任务完成，也不重新决定用户目标、产品路线或跨阶段设计。

开始前确认评审合同能够确定准确的基线和候选、变更应当产生的可观察结果、已接受的设计或约束、实际差异，以及已经取得的测试和运行证据。缺少会改变结论的内容时，要求补足或者给出“证据不足”，不猜测作者意图。

审查主干

1. 确定对象。 核实比较的基线与候选版本、未提交改动和实际差异。目标变化后重新建立范围。只读足以理解设计的周边代码，不把一次审查扩展为全仓库审计。
2. 恢复合同。 读取会决定结论的项目规则、接口、测试、文档、设计记录和调用方。区分已证实事实、作者主张与尚未验证的假设。
3. 从后果生成风险面。 先检查正确性、必需行为、数据保护、权限和生命周期，再考虑可维护性与风格。按变更实际触及的机制选择检查，不机械跑固定清单。
4. 验证证据强度。 测试、构建和静态检查只能证明各自覆盖的层级。任务要求真实宿主、加载器、界面、外部服务或模型调用时，确认是否已有该路径的可观察证据。没有时标明未验证，不把代理指标说成完成。
5. 作出评审结论。 根据实际问题和证据强度给出“可合入”“要求修改”或“证据不足”。只报告本次改动引入或暴露、且作者可纠正的问题。按严重程度说明问题、准确位置、触发条件、影响和需要修正的机制。

局部、机械且结果唯一的改动可以轻量执行上述流程。功能、接口、状态或系统结构变更必须完成足以判断整体方向的审查。

评审结论

• 可合入： 声明的评审范围内没有阻塞问题，而且证据足以支持该范围的正确性和交付声明。
• 要求修改： 有事实和影响支撑的问题表明合同没有满足，或者当前候选不能安全合入或阶段交付。
• 证据不足： 缺少准确评审对象、决定性合同、相关实现或与声明相称的验证证据。没有发现问题不等于证据充分。

把阻塞问题与非阻塞建议分开。候选在评审后发生可能影响结论的变化时，重新确认基线和差异，并复审受影响的范围；不为无关变化重复整个审查。

常见风险的检查方向

• 异步、回调、子进程或释放： 追踪创建、发布、取消、报错和清理。检查竞态、重复回调、所有权和销毁后的工作。
• 接口、配置或权限： 同时追踪提供方与所有调用方。确认默认值和公开能力有当前消费者或明确合同支撑，并沿拒绝路径检查所有可执行入口。
• 状态、缓存或派生视图： 确定权威来源、更新时点、所有通知与读取视图。防止旧值、借用值或失败状态被当作成功结果。
• agent prompt、工具 schema 或 transcript： 把模型可见文本和参数当作行为协议，核对模型实际收到的提示、schema、结果和诊断，并用 snapshot 或真实链路验证适用部分。
• 加载、注册、CLI 或外部集成： 关注实际发布入口，而不是只测试手工组装的函数。检查导出、配置、注册和失败诊断。
• 边界与输出： 对长度、字节数、批量、异常输入和包装层，检查限制是否覆盖最终发出或保存的完整结果。
• 文档和可见文字： 核对配置、默认值、错误、事件和公共行为是否同步。逐项判断可见文字是否帮助使用者识别状态、作出判断或采取行动，避免把提示词、需求理由、验收解释、设计自述或实现辩护当作产品内容。产品语义需要由结构和行为保持时，不要求把合同原句显示出来。
• 实现范围和复杂度： 检查改动是否复用了现有可靠机制，新增代码是否只填补当前结果所需的缺口。为未来需求增加的抽象、配置、兜底和与当前目标无关的重构，会扩大维护面而没有支撑本次结果时，作为问题报告。

不要求为每一类风险制造测试或意见。只在本次改动触及它且证据会改变合入结论时深入。

评审独立性

不采信作者对正确性的自述，不提供补丁，不替上级重定用户目标或产品方向。技术事实、项目规则和可复现证据高于个人偏好。已被可靠自动检查完全覆盖的纯机械问题不重复报告。实现负责人可以用技术证据反驳发现；未经修复、证据反驳或上级明确改变合同的阻塞问题不得被静默忽略。