代码评审记录的价值在于把一次评审的关键信息固定下来：改了什么、谁看过、检查了什么、发现了哪些问题、是否满足合入条件。本文给出一份虚构团队完成一次功能变更后的完整填写范例，逐项解释字段的填写理由，并说明换到不同团队时哪些结构可以保留、哪些需要按实际情况调整。文中情景为演示用途，不代表任何真实项目或客户案例。
要点总览（TL;DR）
- 代码评审记录应固定四组信息：变更范围与提交标识、评审人及视角分工、检查项与结论、问题清单与合入条件，缺一组就难以支撑合入判断和事后追溯。
- 示例中提交范围写到分支加提交区间，检查项绑定到文件与行号，问题按高、中、低分档并对应阻断、合入前完成、后续处理三种处理方式。
- 换团队时保留变更标识、关联需求、评审视角、检查项、问题清单、合入结论这组骨架，按团队规模调整评审人数与角色，按技术栈替换检查项条目。
- 示例为虚构情景，涉及合规审计、安全评审或工具落地时，记录要求与字段配置需按所在组织制度和实际系统另行确认。
示例目标：这份评审记录要解决什么问题
先交代示例的设定。某研发团队正在开发一个订单模块，开发人员提交了一次涉及优惠券计算逻辑的功能变更。变更涉及三个代码文件、一个数据库字段调整和一段接口返回格式的修改。团队采用分支开发、合并前评审的方式，评审记录需要随变更一起留存。
这份记录要回答四个问题：第一，这次变更具体改了什么，范围是否清楚；第二，谁参与了评审，各自从什么视角检查；第三，评审中发现了哪些问题，严重程度如何，由谁在什么时间前修改；第四，这次变更能否合入，合入前还需要完成哪些动作。四个问题对应记录的四组字段，缺一组，记录就无法支撑后续的合入判断和追溯。
需要说明的是，以下团队名称、人员、分支、提交编号和问题内容均为虚构，仅用于演示字段如何填写。示例不涉及任何真实客户、真实项目数据或量化成效。
完整示例：一次功能变更的代码评审记录
下面是一份填写完整的评审记录。为便于阅读，按基本信息、评审分工、检查项、问题清单、合入结论五部分呈现，实际使用时可以合并为一张表单或一个工作项。
基本信息
| 字段 | 填写内容 |
|---|---|
| 变更标题 | 订单优惠券叠加计算逻辑调整 |
| 关联需求/缺陷 | 需求 REQ-1042：支持满减券与折扣券叠加使用 |
| 源分支 | feature/coupon-stack |
| 目标分支 | release/2.8 |
| 提交范围 | a1b2c3d 至 f4e5d6c，共 3 个提交 |
| 变更文件 | coupon_calculator.py、order_service.py、migration_021.sql |
| 提交人 | 开发 A |
| 评审发起时间 | 2025-03-11 10:20 |
评审人与角色分工
| 评审人 | 角色 | 负责视角 |
|---|---|---|
| 开发 B | 模块负责人 | 计算逻辑正确性、边界条件、单元测试覆盖 |
| 开发 C | 同组开发 | 接口兼容性、调用方影响 |
| 测试 D | 测试工程师 | 可测性、异常场景、回归范围 |
| 技术负责人 E | 审批人 | 方案合理性、数据库变更风险、合入决定 |
检查项与逐项结论
| 检查项 | 对应位置 | 结论 |
|---|---|---|
| 叠加计算顺序是否符合需求定义 | coupon_calculator.py 第 45–88 行 | 通过 |
| 金额精度与舍入处理 | coupon_calculator.py 第 90–102 行 | 需修改，见问题 1 |
| 接口返回字段是否向后兼容 | order_service.py 第 210–235 行 | 通过，新增字段为可选 |
| 数据库字段变更是否可回滚 | migration_021.sql | 需补充回滚脚本，见问题 2 |
| 单元测试是否覆盖叠加与互斥场景 | tests/test_coupon.py | 需补充用例，见问题 3 |
| 日志是否包含关键计算入参与结果 | coupon_calculator.py 第 110–118 行 | 通过 |
问题清单
| 编号 | 问题描述 | 严重程度 | 责任人 | 修改要求 | 截止时间 |
|---|---|---|---|---|---|
| 1 | 折扣券金额舍入使用四舍五入，与财务口径的向下取整不一致 | 高（阻断合入） | 开发 A | 改为向下取整，并补充对应单元测试 | 2025-03-12 18:00 |
| 2 | 数据库新增字段缺少回滚脚本 | 高（阻断合入） | 开发 A | 补充 down 脚本并在测试库验证 | 2025-03-12 18:00 |
| 3 | 缺少满减券与折扣券互斥场景的测试用例 | 中（合入前完成） | 开发 A | 补充至少 2 个互斥场景用例 | 2025-03-13 12:00 |
| 4 | 日志中优惠券 ID 字段命名与既有规范不一致 | 低（可后续处理） | 开发 A | 下次迭代统一调整 | 不阻断本次合入 |
合入结论与后续动作
| 字段 | 填写内容 |
|---|---|
| 评审结论 | 有条件通过：问题 1、2 修改并复核后允许合入；问题 3 在合入前完成；问题 4 转入后续任务 |
| 复核人 | 开发 B（问题 1、3）、技术负责人 E（问题 2） |
| 复核方式 | 在源分支追加提交后，由复核人查看差异并回复确认 |
| 合入条件 | 问题 1、2 关闭，问题 3 用例通过，持续集成流水线通过 |
| 后续动作 | 问题 4 登记为技术债任务，排入 2.9 迭代 |
| 记录状态 | 待复核 |
逐项解释：每个字段为什么这样填
变更范围与提交标识要写到可定位的程度。示例中同时写了分支名和提交区间，是因为分支会继续追加提交，只写分支名无法确定评审的是哪一版代码。提交区间配合变更文件列表，让后续复核的人能直接对照差异，也避免评审后新增的提交被默认为已评审。关联需求编号的作用是把技术变更挂回业务上下文，合入后追溯问题时可以快速找到变更动机。
评审人按视角分工，而非按人数凑齐。示例中四个人分别覆盖逻辑正确性、接口兼容性、可测性和方案风险，每个视角都有明确负责人。这样填的好处是检查项可以对应到人，出现遗漏时能判断是哪个视角没有覆盖。团队人数少时，一个人可以承担多个视角，但视角本身不宜省略，否则记录会退化为一句“已评审”。
检查项要绑定到具体代码位置。示例中每条检查项都写了文件与行号范围，结论分为通过、需修改两类。绑定位置的意义在于让结论可核验：复核人不需要重新通读全部变更，只需查看被标记的位置。检查项本身应来自团队约定的清单，覆盖逻辑、兼容性、数据变更、测试和可观测性等维度，而不是每次评审临时想。
问题严重程度直接决定是否阻断合入。示例把问题分为高、中、低三档：高为阻断合入，必须修改并复核；中为合入前完成，可与修改并行推进；低为可后续处理，转入独立任务。严重程度与责任人、截止时间写在同一行，是为了让每个问题都有明确的关闭条件。只写“建议修改”而不标严重程度，会让合入判断失去依据。
结论字段要与责任人和时间绑定。“有条件通过”比“通过”或“不通过”更贴近实际：它明确列出哪些条件满足后才能合入，每个条件对应哪位复核人、以什么方式确认。记录状态单独设一个字段，用于区分“评审中”“待复核”“已关闭”，使记录本身可以随修改进展更新，而不是评审结束就静止。
当评审记录需要与代码变更、需求任务和合入状态放在同一处管理时，可以借助 ONES 工作项承载记录字段，把评审结论、问题清单和复核状态与关联需求、提交信息放在同一条流程里流转，减少记录与实际进展脱节的情况。具体字段配置与状态设置需按团队实际使用的系统核对。
可迁移规律：换一个团队怎么改这份记录
示例中有几组字段属于通用骨架，换团队时建议保留：变更标识（分支加提交区间）、关联需求或缺陷、评审人及视角、检查项与结论、问题清单（含严重程度、责任人、截止时间）、合入结论与复核条件。这些字段共同支撑“改了什么、谁看过、发现什么、能否合入”四个问题，与团队规模和技术栈无关。
随团队情况变化的字段主要有三类。第一类是评审人数与角色，小团队可以合并视角，大团队可以按服务或模块拆分评审人。第二类是问题严重程度的分档方式，有的团队用三级，有的用“阻断/非阻断”两级，关键是分档与合入规则一一对应。第三类是结论的粒度，流程轻的团队可以只保留“通过/有条件通过/不通过”，流程重的团队可以增加审批节点和会签要求。
检查项需要按技术栈和风险调整。示例针对的是业务逻辑与数据库变更，检查项偏重计算正确性、兼容性和回滚能力。如果变更集中在前端交互，检查项应转向可访问性、浏览器兼容和状态管理；如果涉及对外接口，应增加版本兼容与限流降级检查；如果涉及安全敏感模块，应增加权限校验与数据脱敏检查。调整方法是保留检查项的结构，替换具体条目。
记录与合入动作的衔接方式也因团队而异。轻量做法是在合并请求描述中引用记录链接，合入前由审批人确认条件已满足；较重做法是把记录状态与流水线检查绑定，条件未关闭时阻止合入。两种做法都要求记录中的“合入条件”可被逐条核对，这是衔接能否成立的前提。
适用边界：示例不能直接照搬的地方
本文示例为虚构情景，人员、分支、提交编号和问题内容均为演示而设，不代表任何真实项目的评审过程或改进成效。读者可以参照字段结构和填写思路，但不能把示例中的结论、分档或时间要求当作行业标准。
涉及合规、审计或安全评审的场景，通常有额外的记录要求，例如评审人资质、留痕期限、审批层级和独立的检查清单。这些要求需要按所在组织的制度另行确认，示例中的字段可以作为起点，但不构成合规依据。
工具承载方式同样需要按实际系统核对。评审记录放在代码托管平台的合并请求中、放在项目管理工具的工作项中，还是两者关联，字段名称、必填规则和状态流转都会不同。示例中的字段是内容层面的建议，落地到具体系统时，应以系统实际支持的配置为准，涉及版本、部署方式或集成能力的信息需另行确认。
此外，示例聚焦评审记录与合入判断，不涉及代码优化技巧、算法选择或评审等待时长等流动效率指标。这些内容有各自的分析方法，不宜从本示例中推导。
常见问题
评审记录里的提交范围只写分支名可以吗？
不建议只写分支名。分支在评审期间会继续追加提交，只写分支名无法确定评审的是哪一版代码，评审后新增的提交容易被默认为已评审。示例采用分支名加提交区间的方式，例如从 a1b2c3d 到 f4e5d6c，再配合变更文件列表，复核人就能直接对照差异。如果团队习惯按合并请求评审，也可以记录合并请求编号，但同样要能定位到具体版本。
小团队评审人少，视角分工还需要保留吗？
需要保留视角，人数可以合并。示例中四个人分别覆盖逻辑正确性、接口兼容性、可测性和方案风险，小团队可以由一两个人承担多个视角，但每个视角仍要在记录中写明由谁负责。这样检查项能对应到人，出现遗漏时能判断是哪个视角没有覆盖。如果直接省略视角，记录容易退化成一句“已评审”，后续无法追溯评审质量。
问题严重程度分几档比较合适？
分档数量取决于团队的合入规则，关键是每一档对应一种明确的处理方式。示例用高、中、低三档：高为阻断合入，必须修改并复核；中为合入前完成；低为转入后续任务。流程简单的团队也可以用“阻断/非阻断”两档。无论几档，严重程度都要和责任人、截止时间写在同一行，让每个问题都有可核对的关闭条件。
评审结论写“有条件通过”会不会比直接写通过更麻烦？
“有条件通过”更贴近实际评审状态，它把合入前提逐条列出，每条对应复核人和确认方式，避免把未完成的问题带进主干。代价是记录需要随修改进展更新，记录状态要区分“评审中”“待复核”“已关闭”。如果团队变更频率低、问题很少，也可以只用“通过/不通过”，但一旦出现需要修改的问题，仍要写清关闭条件，否则合入判断缺少依据。
涉及安全或合规要求的变更，这份记录能直接用吗？
可以作为起点，不能直接作为合规依据。合规、审计或安全评审通常有额外要求，例如评审人资质、留痕期限、审批层级和独立的检查清单，这些需要按所在组织的制度另行确认。示例中的字段结构可以帮助组织信息，但具体条目、审批节点和留存方式应以制度规定为准。
