代码工作项追溯记录要回答的是：这次代码改了什么、为什么改、谁改的、谁评审过、是否已经合入。本文用一条演示情景，给出一份已填写的追溯记录，并逐字段说明填写理由，帮助读者在自己的项目中建立或调整记录方式。示例聚焦代码变更与需求、缺陷、任务的对应关系，不展开代码库接入配置与评审合入规则。
要点总览（TL;DR）
- 一份可用的代码工作项追溯记录，至少要能回答改了什么、为什么改、谁改的、谁评审过、是否已合入这五个问题。
- 示例用需求 REQ-1042 与缺陷 BUG-1077 两次提交，演示工作项编号、提交标识、变更说明、关联类型、评审人、状态与时间等字段的完整填法。
- 字段可按团队规模裁剪，但对应关系、责任人、状态三类核心信息建议保留，判断标准是删减后五个问题仍能回答。
- 记录维护落在三个时点：提交时关联工作项、评审时更新结论与状态、合入后核对时间与状态。
- 代码库接入与权限配置、评审合入规则与分支策略属于相邻主题，需要由对应机制另行承担。
示例目标：这份追溯记录要解决什么问题
追溯记录的价值在于把分散在提交历史、工作项描述和评审意见里的信息收拢到一处，让后续核查的人不必逐个系统翻找。一份合格的记录，应当能独立回答五个问题：这次改了什么、为什么改、谁改的、谁评审过、是否已合入。这五个问题对应记录中的变更说明、关联工作项、开发人、评审人和状态字段，缺一项就会在回溯时留下断点。
本文示例设定为演示情景，用于展示填写方法，不代表真实客户案例，也不包含任何实测数据或量化效果。示例覆盖的范围是代码变更与工作项的对应关系：一条提交如何挂到需求或缺陷上，记录哪些字段，状态如何随开发过程变化。代码库如何接入、权限如何分配、分支策略与合入规则如何设计，属于相邻主题，本文只在边界部分说明分工，不给出具体操作。
判断一份记录是否合格，可以用下面的清单自查：
- 每条代码提交都能指向至少一个工作项编号，且关联类型明确；
- 变更说明能说清业务意图，读者不看代码也能理解改动目的；
- 开发人与评审人可查，评审结论有记录；
- 状态字段能反映提交当前处于开发、评审还是已合入阶段；
- 时间字段完整，能还原从提交到合入的先后顺序。
完整示例：一条代码变更的追溯记录怎么填
示例背景设定如下：某订单模块有一个需求“支持订单备注修改”，工作项编号 REQ-1042；测试过程中发现一个缺陷“备注超过 200 字保存失败”，工作项编号 BUG-1077。开发人员针对这两项分别提交了两次代码，第一次提交实现备注修改功能，第二次提交修复长度校验缺陷。以下记录表展示这两次提交的完整填写结果，均为演示情景。
| 字段 | 记录一（对应需求） | 记录二（对应缺陷） |
|---|---|---|
| 工作项编号 | REQ-1042 | BUG-1077 |
| 工作项标题 | 支持订单备注修改 | 备注超过 200 字保存失败 |
| 提交标识 | commit a3f9c21 | commit 7d2e0b8 |
| 变更说明 | 新增订单备注编辑入口与保存接口，备注字段上限 200 字 | 修正备注长度校验，超长时返回提示而非保存失败 |
| 关联类型 | 需求 | 缺陷 |
| 开发人 | 开发 A | 开发 A |
| 评审人 | 开发 B | 开发 B |
| 评审结论 | 通过，建议补充空备注的边界处理 | 通过 |
| 状态 | 已合入 | 已合入并验证 |
| 提交时间 | 第 1 天 10:20 | 第 3 天 14:05 |
| 评审时间 | 第 1 天 16:40 | 第 3 天 17:30 |
| 合入时间 | 第 2 天 09:15 | 第 4 天 10:00 |
从状态变化看，记录一经历了“开发中→待评审→已合入”的过程：提交后进入评审，评审通过后次日合入。记录二在合入后增加了验证环节，状态记为“已合入并验证”，表示缺陷修复已经过回归确认。两条记录共用同一开发人与评审人，便于按人检索；时间字段按天与时刻记录，足以还原先后顺序。实际使用时，提交标识应填写团队代码平台中可唯一定位该次提交的编号或短哈希。
逐项解释：每个字段为什么这样填
工作项编号与提交标识。这两个字段构成记录的主键组合：工作项编号指向“为什么改”，提交标识指向“改了什么”。示例中 REQ-1042 与 commit a3f9c21 成对出现，任何人拿到这条记录，都能从工作项追到具体提交，也能从提交反查它服务的工作项。填写时保持编号与代码平台中的标识一致，避免使用“需求一”“第一次提交”这类无法检索的称呼。
变更说明。示例中写的是“新增订单备注编辑入口与保存接口，备注字段上限 200 字”，而不是罗列改动了哪些文件。业务意图写在说明里，回溯时不必读代码就能判断这次改动是否与需求一致；文件清单可以由提交本身承载，记录里重复价值不大。缺陷记录的说明写“修正备注长度校验，超长时返回提示”，点明了修复的具体行为。
关联类型。需求、缺陷、任务三类工作项的处理节奏不同：需求关注功能是否交付，缺陷关注问题是否消除，任务关注计划内工作是否完成。示例把两次提交分别标为需求与缺陷，后续统计需求交付情况或缺陷修复周期时，可以直接按类型筛选，不必再人工判断。
评审人与评审结论。评审人字段回答“谁看过这次改动”，评审结论记录通过与否以及遗留意见。示例中记录一附带了“建议补充空备注的边界处理”，这条意见让后续核查的人知道该提交存在已知的待完善点，避免把评审通过误解为毫无保留。
状态与时间。状态字段支撑进度核查：待评审的提交需要跟进，已合入的提交可以进入验证。时间字段则还原过程，示例中提交、评审、合入三个时点分开记录，可以算出评审等待时长和合入周期，用于观察流程是否顺畅。只记一个“完成时间”会丢失中间环节的信息。
可迁移规律：换一个项目怎么复用这套记录
示例中的字段可以按团队规模和流程裁剪，但三类核心信息建议保留：对应关系（工作项编号与提交标识）、责任人（开发人与评审人）、状态（当前阶段与关键时间）。小团队可以合并评审人与评审结论为一栏，或省略工作项标题；流程较长的团队可以增加验证人、关联测试用例等字段。裁剪的原则是：删掉字段后，前面列出的五个问题仍能回答。
书写约定比字段数量更影响记录质量。建议在团队内约定两条规则：提交说明采用“工作项编号 + 动作 + 对象”的结构，例如“REQ-1042 新增订单备注保存接口”；工作项描述中写清验收标准，使变更说明有可对照的依据。约定形成后，记录填写从个人习惯变成团队惯例，检索和统计才有稳定基础。
记录维护有三个关键时点：提交代码时完成工作项关联，此时对应关系最清晰；评审结束时更新评审结论与状态，避免记录停留在“待评审”；合入后核对状态与时间，确认记录与实际一致。这三个动作分别由开发人和评审人承担，责任明确后不容易遗漏。
记录积累起来后有两种直接用途。编写发布说明时，按时间范围筛选已合入记录，按关联类型分组，即可得到“本次发布包含哪些需求、修复了哪些缺陷”的清单。问题回溯时，从故障现象定位到相关提交，再沿提交标识找到工作项与评审意见，能较快还原改动背景和决策过程。
在工具层面，这类记录可以依托工作项与代码提交的关联管理来维护：提交时在提交信息中引用工作项编号，工作项侧即可看到关联的代码变更，状态随评审与合入推进更新，评审意见与时间留存在同一条记录中。ONES 支持工作项与代码提交建立关联，适合把上述字段和状态流转放在同一处维护；具体配置方式以团队实际使用的代码平台与工具版本为准。
适用边界：哪些情况需要补充其他记录
本文示例聚焦代码变更与工作项的对应，有几类相邻工作不在其覆盖范围内，需要由其他机制承担。代码库如何接入研发平台、账号与权限如何分配，属于研发工具链集成范畴，涉及仓库授权、服务账号和安全策略，应参照对应平台的接入文档执行。评审合入规则、分支策略、必过检查项如何设计，属于代码评审与合入管理范畴，本文只记录评审结果，不规定评审如何进行。
多仓库、多服务场景需要额外的关联约定。一次需求变更可能横跨多个仓库的提交，此时仅靠单条提交与工作项的对应不足以还原全貌，建议在工作项中汇总关联的全部提交，或在记录中增加“变更范围”字段标明涉及的仓库与服务。跨团队协作时，还需约定工作项编号的命名规则，避免不同团队编号冲突。
此外，追溯记录本身不构成对任何具体工具能力的确认。示例中的字段、状态与时间口径是通用管理方法，迁移到实际项目时，应以所用工具的实际功能与团队流程为准，必要时补充测试记录、发布记录等配套文档，形成完整的追溯链条。
常见问题
提交信息里只写工作项编号，变更说明还需要单独写吗？
需要。工作项编号解决的是“这条提交服务于哪项工作”，变更说明解决的是“这次改动做了什么、为什么这样做”。两者承担的信息不同，编号无法替代说明。实践中可以在提交信息中同时写编号和一句业务意图，例如“REQ-1042 新增订单备注保存接口”，再把这句话同步到追溯记录中，避免记录与提交历史脱节。
一次提交同时涉及需求和缺陷修复，关联类型怎么填？
建议拆成两条记录，各自关联一个工作项，提交标识填同一个。这样按需求统计交付、按缺陷统计修复周期时都不会混淆。如果团队流程要求一条记录对应一次提交，可以在关联类型中标注主类型，并在变更说明里写明另一项工作项编号，同时在工作项侧补充反向关联，保证从任一方向都能查到这次提交。
小团队没有专职评审人，评审字段可以省略吗？
可以简化，但建议保留“谁确认过这次改动”这一信息。小团队常见的做法是开发人互评，评审人填实际看过代码的同事；如果确实没有独立评审环节，可以保留评审人字段并注明自查，或合并为“确认人”一栏。省略这一字段会让后续回溯失去判断改动质量的依据，尤其在出现问题时难以区分是设计遗漏还是评审遗漏。
记录里的时间字段记到天还是记到时刻？
取决于团队要观察什么。如果只关心提交与合入的先后顺序，记到天通常够用；如果要观察评审等待时长、合入周期这类流程指标，记到时刻更合适。示例中提交、评审、合入三个时点分开记录，就是为了保留中间环节。无论精度如何，同一团队内应保持口径一致，避免部分记录记到天、部分记到时刻，导致统计时无法比较。
多仓库项目里，一条需求对应多个仓库的提交，记录怎么组织？
单条提交与工作项一一对应的记录方式在这种场景下不够用。建议在工作项中汇总关联的全部提交，或在记录中增加“变更范围”字段，标明涉及的仓库与服务，并约定同一需求下各提交的命名或标签规则。跨团队协作时还需统一工作项编号的命名方式，避免不同团队编号重复导致关联错位。
