代码评审记录的价值，在于能回溯“谁在什么版本上提了什么意见、怎么改的、是否合入”。围绕这条主线，一份可用的记录至少保留评审对象与版本、评审过程、问题与处置、合入结果四类信息。本文给出可直接套用的字段清单、字段随流程产生的步骤、角色分工、填写示例与合格性检查清单，并说明记录载体如何与需求、缺陷等工作项衔接。
要点总览（TL;DR）
- 代码评审记录至少保留四组信息：评审对象与版本、评审过程、问题与处置、合入结果，底线是能回溯“谁在什么版本上提了什么意见、怎么改的、是否合入”。
- 字段应随流程自然产生：发起时填对象与参与人，评审中记意见与结论，修改后回填提交并关闭意见，合入时补录结果，避免事后回忆补记。
- 按作者、评审人、合入人、评审组织者划分字段归属，并把归属写进评审模板，比在文档中罗列职责更能减少漏填。
- 记录载体按追溯需求取舍：只需还原代码讨论可用代码平台，需要从需求、缺陷反查评审与合入时，放在工作项系统中更便于关联。
- 合格性检查围绕字段完整性、意见关闭与合入一致性、可追溯性三项展开，抽查不合格的记录应退回补充而非直接归档。
一份可用的代码评审记录包含哪些字段
字段设计不必追求数量，而要以能还原一次评审的完整链路为底线：定位到具体代码状态、还原评审当时的分歧与决策、确认每条意见的处置结果、对应到最终合入动作。以下四组字段分别回答四个问题，可按团队合规要求增补，不建议删减必填项。
第一组：评审对象与版本——评的是哪份代码
这组字段解决“记录能否定位到具体代码状态”的问题。仅有分支名不够，分支会继续前进；提交或变更集标识才是评审时的准确快照。
| 字段名 | 含义 | 是否必填 |
|---|---|---|
| 仓库 | 代码所在仓库名称或地址 | 必填 |
| 源分支 / 目标分支 | 变更来源分支与拟合入分支 | 必填 |
| 提交或变更集标识 | 评审时的代码快照标识，如提交哈希、变更请求编号 | 必填 |
| 基线版本 | 变更所基于的版本或发布基线 | 建议必填 |
| 变更范围摘要 | 涉及模块、文件数量、变更类型（新功能、修复、重构） | 建议填写 |
第二组：评审过程——谁在什么时候评的、结论是什么
这组字段用于还原评审当时的参与情况和决策。评审人名单要记录实际参与人，而非仅记录被指派人；结论字段应明确写出通过、有条件通过或退回修改。
| 字段名 | 含义 | 是否必填 |
|---|---|---|
| 发起人 | 提交评审请求的人 | 必填 |
| 评审人 | 实际参与评审的人员名单 | 必填 |
| 评审时间 | 评审发起时间与结论形成时间 | 必填 |
| 评审意见 | 逐条记录的意见内容，与第三组字段一一对应 | 必填 |
| 评审结论 | 通过、有条件通过、退回修改 | 必填 |
第三组：问题与处置——每条意见怎么处理的
这组字段让意见从提出到关闭形成闭环。每条意见独立成行，严重程度用于区分必须修改项与建议项，修改提交字段把意见与具体代码改动对应起来。
| 字段名 | 含义 | 是否必填 |
|---|---|---|
| 意见编号 | 意见的唯一标识，便于引用与追踪 | 必填 |
| 严重程度 | 阻断、重要、建议等分级 | 必填 |
| 责任人 | 负责处置该意见的人 | 必填 |
| 修改提交 | 处置该意见对应的提交标识 | 必填（建议类意见可注明不修改及理由） |
| 关闭状态 | 待处理、已修改待确认、已关闭、不修改 | 必填 |
| 关闭确认人 | 确认意见已解决的人 | 建议必填 |
第四组：合入结果与关联——最终是否进了目标分支
评审通过不等于已合入。这组字段把评审结论与交付结果对应起来，并通过关联需求或缺陷，让后续追溯能从代码改动反查到业务背景。
| 字段名 | 含义 | 是否必填 |
|---|---|---|
| 合入人 | 执行合入操作的人 | 必填 |
| 合入时间 | 实际合入的时间 | 必填 |
| 目标分支 | 代码最终进入的分支 | 必填 |
| 合入提交标识 | 合入后的提交或合并记录标识 | 必填 |
| 关联需求 / 缺陷 | 本次变更对应的需求单、缺陷单或任务编号 | 必填 |
从发起到合入：记录怎么产生和流转
字段应随评审流程自然产生，避免事后补记。每个环节都有明确的输入、动作、输出和完成标志，记录在流程推进中逐步填满，而不是在结束时一次性回忆填写。
第一步：发起评审时填写对象与参与人
- 输入：已完成的代码变更、对应的需求或缺陷编号。
- 动作：发起人创建评审记录，填写仓库、源分支与目标分支、提交或变更集标识、基线版本、变更范围摘要，指定评审人并写明评审关注点。
- 输出：一条状态为“待评审”的记录，第一组字段完整。
- 完成标志：评审人能凭记录中的版本标识直接定位到待评代码。
第二步：评审中逐条记录意见与结论
- 输入：待评审的代码快照、评审关注点。
- 动作：评审人阅读变更，按意见逐条登记：意见内容、严重程度、责任人；全部意见登记完毕后给出评审结论。
- 输出：第二组字段完整，第三组字段中每条意见处于“待处理”状态。
- 完成标志：评审结论已明确，且每条意见都有责任人和严重程度。
第三步：修改后回填提交并关闭意见
- 输入：评审意见清单。
- 动作：作者逐条修改代码，在对应意见下回填修改提交标识，将状态改为“已修改待确认”；评审人复核后改为“已关闭”，建议类意见若不采纳，需写明理由并将状态记为“不修改”。
- 输出：第三组字段中不再有“待处理”意见。
- 完成标志：所有阻断与重要级意见均已关闭，且每条关闭意见都能对应到具体提交。
第四步：合入时补录结果信息
- 输入：评审结论为通过或有条件通过且条件已满足的记录。
- 动作：合入人执行合入，补录合入人、合入时间、目标分支、合入提交标识，确认关联需求或缺陷编号无误。
- 输出：第四组字段完整，记录状态更新为“已合入”。
- 完成标志：从记录可一路追溯到合入提交，且关联工作项状态同步更新。
角色分工与各自要交付的记录内容
字段无人填写，通常是因为职责没有落到具体角色。按作者、评审人、合入人、评审组织者四类角色划分字段归属，每个角色在固定时机交付固定内容，可以减少遗漏。
| 角色 | 负责字段 | 填写时机 | 交付物 |
|---|---|---|---|
| 作者（发起人） | 仓库、分支、提交标识、基线版本、变更范围摘要、关联需求或缺陷；意见的修改提交与处置说明 | 发起评审时；收到意见后修改期间 | 完整的评审对象信息；每条意见的修改提交对应关系 |
| 评审人 | 评审意见、严重程度、责任人建议、评审结论、关闭确认 | 评审过程中；复核修改时 | 逐条意见清单与明确结论；意见关闭确认 |
| 合入人 | 合入人、合入时间、目标分支、合入提交标识 | 执行合入时 | 可核对的合入结果记录 |
| 评审组织者 / 负责人 | 评审人名单的完整性、结论与意见状态的一致性、记录归档前的整体检查 | 评审发起前；合入前；定期抽查时 | 检查结论；不合格记录的退回意见 |
分工确定后，建议把字段归属写进评审模板：发起页面只出现作者应填的字段，评审页面突出意见登记区，合入环节单独设置结果确认区。模板按角色分区，比在文档中罗列职责更能减少漏填。
一个完整示例：小需求变更的评审记录
以下为演示情景，用于说明字段如何填写，不代表真实客户案例。背景：订单服务需要增加“超时未支付自动取消”逻辑，作者在功能分支完成开发后发起评审。
评审对象与过程信息
- 仓库：order-service；源分支：feature/auto-cancel；目标分支：release/2.4。
- 提交标识：a1b2c3d；基线版本：release/2.3；变更范围：订单状态机与定时任务，共修改 6 个文件。
- 发起人：作者甲；评审人：乙、丙；评审时间：发起当日与次日完成评审。
- 关联需求：需求单 REQ-1042“超时未支付订单自动取消”。
两条典型意见的记录方式
| 意见编号 | 意见内容 | 严重程度 | 责任人 | 修改提交 | 关闭状态 |
|---|---|---|---|---|---|
| R1 | 取消操作与支付回调存在并发窗口，可能误取消已支付订单，需加状态校验 | 阻断 | 作者甲 | d4e5f6a | 已关闭（评审人乙确认） |
| R2 | 定时任务扫描间隔建议改为可配置，便于不同环境调整 | 建议 | 作者甲 | d4e5f6a | 已关闭（评审人丙确认） |
评审结论记为“有条件通过”：R1 关闭后方可合入。作者提交 d4e5f6a 后，两条意见分别由对应评审人复核关闭，记录中不再有未处理意见。
合入结果与需求关联
- 合入人：作者甲；合入时间：意见全部关闭后的当日；目标分支：release/2.4。
- 合入提交标识：m7h8i9j；关联需求 REQ-1042 状态同步更新为“已交付待验证”。
这份记录可以完整回答：在 a1b2c3d 这个版本上，两位评审人提出了什么意见、作者用哪个提交修改、谁确认关闭、最终以哪个提交进入 release/2.4、对应哪条需求。
记录放在哪里、如何与工作项衔接
记录载体的选择取决于追溯需求。若只需还原代码层面的讨论，代码平台的评审功能即可承载；若需要从需求、缺陷反查评审与合入情况，把记录放在工作项系统中更便于关联。常见做法是两者并用：代码平台保留行级讨论，工作项系统保存结构化字段与结论。
三种载体的取舍
| 载体 | 适合场景 | 需要注意 |
|---|---|---|
| 代码平台评审功能 | 以代码讨论为主、团队规模较小 | 结构化字段有限，跨需求追溯需额外整理 |
| 专用评审工具 | 对评审流程有专门规范、需要统计评审活动 | 需与代码平台和工作项系统建立关联，避免形成信息孤岛 |
| 工作项系统 | 需要与需求、缺陷、任务联动追溯 | 行级代码讨论仍需代码平台承载，两边通过提交标识关联 |
与需求、缺陷、任务的关联方式
关联的核心是双向可查：从需求单能看到它经过哪些评审、合入了哪些提交；从评审记录能反查到对应需求与缺陷。实现方式通常是在评审记录中填写关联工作项编号，并在工作项中回写评审记录链接或合入提交标识。状态流转上，建议约定“评审通过且意见关闭”才允许工作项进入待合入或已完成状态，让记录状态与工作项状态保持一致。
ONES 在其中的承载方式
当团队把需求、任务、缺陷统一放在 ONES 中管理时，评审记录可以作为工作项下的一类过程信息保存：作者在需求或任务下发起评审并填写版本与参与人，评审意见与处置结果随工作项流转记录，合入后回填结果字段并更新工作项状态。这样，需求、评审记录与合入结果处在同一条工作项链路上，追溯时无需在多个系统间拼接信息。具体字段配置与状态流转方案，可结合团队现有的工作项类型设计。
完成检查：记录是否合格的核对项
检查可在合入前由评审组织者执行，也可按周或按迭代抽查。以下清单按三类核对项组织，每项给出通过标准，便于逐条判断。
字段完整性检查
- 仓库、源分支、目标分支、提交或变更集标识均已填写，且能定位到评审时的代码快照。
- 发起人、评审人、评审时间、评审结论齐全，评审人为实际参与人。
- 每条意见都有严重程度、责任人和关闭状态，不存在空白项。
- 合入人、合入时间、目标分支、合入提交标识、关联需求或缺陷均已补录。
意见关闭与合入一致性检查
- 阻断与重要级意见全部处于“已关闭”状态；标记“不修改”的意见写明了理由并经评审人确认。
- 每条关闭意见都能对应到具体修改提交，提交存在于目标分支的合入历史中。
- 评审结论为“退回修改”的记录没有合入结果；结论为“有条件通过”的记录，条件已满足后才出现合入信息。
- 合入提交标识与评审时的提交标识之间的差异，能由意见修改解释。
可追溯性检查
- 从关联需求或缺陷可以查到本次评审记录与合入提交。
- 从合入提交可以反查到评审记录及对应工作项。
- 记录中的时间顺序合理：发起早于评审结论，意见关闭早于合入。
不合格记录的处理方式
抽查发现缺项的记录应退回补充，而不是直接归档：缺少版本标识的，由作者补填提交标识；意见未关闭的，退回责任人处理并由评审人确认；合入信息缺失的，由合入人补录。退回时在记录中注明缺项与补填期限，补填完成后重新核对。对反复出现同类缺项的团队，可回到模板层面调整必填项与角色分区，从源头减少漏填。
常见问题
小团队评审频率不高，字段能不能精简？
可以精简，但建议保留能支撑回溯的最小集合：仓库、源分支与目标分支、提交或变更集标识、发起人与评审人、评审结论、每条意见的严重程度与关闭状态、合入提交标识和关联需求或缺陷。基线版本、变更范围摘要、关闭确认人等字段在团队规模小、变更简单时可先作为建议项。判断标准是：事后有人问“这条意见改在哪个提交、最终进了哪个分支”，记录能否直接回答。
评审意见在代码平台里讨论，还需要另建结构化记录吗？
取决于追溯需求。若只需要还原代码层面的讨论，代码平台的行级评论已能承载；若需要从需求或缺陷反查评审与合入情况，行级讨论难以按工作项汇总，建议另存一份结构化记录，至少包含版本标识、结论、意见关闭状态与合入结果，并通过提交标识与代码平台关联。两边并用时，注意约定哪一边是权威来源，避免同一意见在两处状态不一致。
建议类意见作者不打算修改，记录里怎么处理？
不建议直接删除或留空。把该意见的关闭状态记为“不修改”，在处置说明中写明不修改的理由，并由评审人确认。这样记录既保留了评审当时提出过的问题，也说明了团队的决策依据。检查时，标记“不修改”的意见应与阻断、重要级意见区别对待：前者核对理由与确认人，后者要求全部关闭。
评审通过后代码迟迟没有合入，记录状态怎么管？
评审结论与合入结果是两组独立字段，评审通过只更新结论，合入人、合入时间、合入提交标识在真正执行合入时才补录。中间这段时间记录处于“已通过待合入”状态，便于识别积压。若变更长期未合入，可回到评审环节确认代码是否已与目标分支产生较大差异，必要时重新发起评审，而不是沿用旧结论直接合入。
定期抽查发现记录缺项，应该补记录还是改流程？
两者都要做，顺序上先补记录、再改流程。缺版本标识的由作者补填提交标识，意见未关闭的退回责任人处理并由评审人确认，合入信息缺失的由合入人补录，补填后在记录中注明缺项与期限。若同类缺项反复出现，说明模板或角色分区有问题，应调整必填项设置和页面分区，让对应角色在固定时机只看到自己该填的字段。
