代码工作项追溯记录的价值，在于把一次代码变更和它对应的需求、缺陷或任务用可核对的字段固定下来，让后续查问题时能顺着记录找到业务意图与代码事实。本文给出一份已填写的演示示例，逐项说明字段填写依据，并提炼可迁移到不同团队的规则。示例为演示情景，非真实客户案例。
要点总览（TL;DR）
- 追溯记录围绕四个问题设计字段：对应哪个工作项、改了哪些代码、谁验证过、是否已合入，分别对应业务意图、代码事实、质量证据和交付状态。
- 完整示例以一次合并请求对应一条主记录，包含工作项编号与类型、代码库与分支、提交号、合并请求、变更说明、关联方式、验证结论、合入状态、责任人与时间。
- 字段填写的关键是写可核对的内容：编号代替标题，提交号与合并请求并列，验证结论写清验证方式与执行人，责任人区分提交人、评审人、验证人。
- 迁移到不同团队时，按工作项类型调整字段取舍，多工作项变更采用主从记录，记录位置依主要使用者的检索习惯选择，编号格式保持稳定。
- 紧急修复可事后补录并注明原因，批量重构按合并请求记主记录，套用前需核对所用平台的实际字段与关联方式。
示例目标：一份追溯记录要回答哪几个问题
追溯记录要回答四个问题：这次变更对应哪个工作项、改了哪些代码、谁验证过、是否已经合入。四个问题分别对应业务意图、代码事实、质量证据和交付状态，缺一项，记录就只能算半份。字段设计围绕这四个问题展开，而不是为了填满表格。
本示例设定为演示情景：某团队在一个需求工作项下调整了接口字段，从提交到合入形成一条完整记录。文中出现的编号、人员、时间均为示意，用于说明填写方式，不代表任何真实项目。
记录粒度建议以一次合并请求对应一条主记录。合并请求是代码进入主干的最小可评审单元，围绕它记录，业务意图与代码事实的对应关系最清晰。团队若采用更细的提交级记录或更粗的版本级记录，可在此基础上调整，这属于协作方式选择，不是统一要求。
判断一份记录是否合格，可以用三个标准核对：工作项编号能在业务侧查到，提交号与合并请求能在代码库查到，验证结论与合入状态能对应到具体的人和动作。三条都能对上，记录才具备可追溯性。
完整示例：一条代码变更追溯记录
示例背景：需求工作项“订单查询接口增加收货地址字段”进入开发，开发人员在功能分支完成字段调整，提交合并请求，经评审与验证后合入主干。下表是填写完成后的记录，可直接对照格式使用。
| 字段 | 填写内容（演示） |
|---|---|
| 工作项编号 | REQ-2041 |
| 工作项类型 | 需求 |
| 工作项标题 | 订单查询接口增加收货地址字段 |
| 代码库 | order-service |
| 分支 | feature/REQ-2041-address-field |
| 提交号 | a1b2c3d（接口返回体新增 address 字段） |
| 合并请求 | MR-318，目标分支 main |
| 变更说明 | 订单查询接口返回体新增收货地址字段，兼容旧字段，未改动入参 |
| 关联方式 | 提交信息引用工作项编号，合并请求描述中再次引用 |
| 验证结论 | 接口联调通过，旧字段回归用例全部通过，验证人：测试-李 |
| 合入状态 | 已合入 main，合入时间 2025-03-12 |
| 责任人 | 提交人：开发-王；评审人：开发-赵；验证人：测试-李 |
| 时间 | 提交 2025-03-10，评审通过 2025-03-11，合入 2025-03-12 |
这条记录从提交到合入形成闭环：工作项编号把代码变更挂回业务需求，提交号与合并请求锁定代码事实，验证结论给出质量证据，合入状态与时间说明交付结果。查记录的人不需要再问开发人员，就能还原这次变更的来龙去脉。
逐项解释：每个字段为什么这样填
工作项编号与类型要写唯一编号，避免只写标题。标题可能被修改，也可能存在同名需求，编号才是稳定对应关系。类型字段决定这条记录按需求、缺陷还是任务的语境理解，影响后续统计与检索口径。
提交号与合并请求承担不同职责。提交号记录代码层面实际发生了什么，合并请求记录这次变更被如何评审与合入。只写合并请求，细粒度改动难以定位；只写提交号，评审过程与合入结论缺失。两者并列，代码事实与业务意图才能互相印证。
关联方式有三种常见写法，差别如下：
| 关联方式 | 做法 | 适用与注意点 |
|---|---|---|
| 提交信息引用 | 在提交说明中写入工作项编号 | 粒度细，但依赖提交规范执行 |
| 合并请求描述引用 | 在合并请求描述中写明工作项编号与变更摘要 | 评审时可见，适合作为主关联位置 |
| 平台自动关联 | 由研发管理平台根据编号规则建立关联 | 减少手工填写，具体能力依平台配置而定 |
验证结论要记录证据，不写“已验证”这类口头确认。写清验证了什么、用什么方式、谁执行的，例如联调通过、回归用例通过、验证人姓名。合入状态同理，写“已合入 main”并附时间，比写“完成”更有核对价值。
责任人与时间要区分三类角色：提交人、评审人、验证人。三者合一在小型团队中常见，但记录上仍应分别标明，否则出问题时无法判断哪个环节缺失。时间字段至少保留提交、评审通过、合入三个节点，便于还原节奏。
常见错误写法包括：只写工作项标题不写编号；变更说明写成“修改代码”“优化逻辑”这类无法核对的内容；验证结论只写结论不写依据；责任人与时间合并成一个字段。这些写法让记录看起来完整，实际无法支撑追溯。
可迁移规律：换一个团队怎么套用
需求、缺陷、任务三类工作项的字段取舍有差异。需求类记录侧重变更说明与验证结论，因为需求变更需要说明范围；缺陷类记录侧重复现条件与修复验证，验证结论要写清原缺陷是否复现；任务类记录可简化变更说明，保留提交号、合并请求与合入状态即可。字段数量可以不同，编号、代码事实、状态三类信息应保留。
一次变更涉及多个工作项时，建议采用主从记录写法：以承载主要业务意图的工作项为主记录，完整填写全部字段；其余工作项作为从记录，只写主记录编号与本次涉及的改动点。这样避免同一份变更在多处重复描述，也保留每个工作项的对应关系。
记录放在工作项侧还是代码侧，取决于团队查记录的入口。业务人员从工作项出发查变更，记录应放在工作项侧；开发人员从代码出发查意图，记录应靠近合并请求。两侧都放摘要、以一侧为主记录，是较常见的折中做法。选择依据是主要使用者的检索习惯，不是固定规则。
命名与编号约定要保持稳定。分支名带工作项编号、提交信息引用编号、合并请求描述引用编号，三处使用同一编号格式，自动关联与人工检索才能生效。约定一旦确定，中途更换格式会让历史记录断链，迁移成本高于初期统一。
在研发管理平台中承载这类记录时，可以把工作项作为主对象，将提交号、合并请求、验证结论与合入状态作为关联信息随状态流转更新。ONES 支持工作项与研发过程信息的关联管理，具体字段与关联形式依实际配置而定，团队可先按本文示例确定字段口径，再落到平台中执行。
适用边界：哪些情况不适合这样记录
本文示例聚焦记录本身的字段与写法。代码库接入、权限配置属于研发工具链集成范畴，评审合入规则的设计与门禁配置属于代码评审与合入管理，本文只在记录中体现结果，不展开这些操作。
紧急修复场景可以简化记录：先提交修复并合入，事后补录工作项编号、变更说明与验证结论，补录时注明“事后补录”及原因。批量重构涉及大量文件时，按合并请求记一条主记录、在变更说明中列出影响范围，比逐文件记录更可维护。简化不等于省略，编号、代码事实与合入状态仍应保留。
不同工具的字段能力存在差异，示例中的字段并非每个平台都以独立字段呈现，部分信息可能写在描述或备注中。团队套用前应核对所用平台的实际字段与关联方式，按可用能力调整记录结构，不必强求与示例逐字段一致。
常见问题
工作项编号在提交信息和合并请求描述里都写，会不会重复？
两处都写是有意为之，不算冗余。提交信息中的编号把细粒度代码改动挂回工作项，合并请求描述中的编号在评审环节提供业务上下文，两者服务不同读者和不同检索入口。团队也可以约定以合并请求描述为主关联位置，提交信息保留编号作为辅助，关键是同一编号格式在分支名、提交信息、合并请求描述三处保持一致，避免历史记录断链。
一次提交同时涉及需求改动和缺陷修复，追溯记录应该挂在哪一类工作项下？
按变更的主要业务意图确定主记录所属工作项，另一类工作项作为从记录，只写主记录编号和本次涉及的改动点。如果两部分改动可以拆成独立的合并请求，拆开分别记录更清晰；如果确实耦合在一个合并请求里，主记录中在变更说明里分段写清两部分内容，并分别标注对应的工作项编号，便于后续按类型检索。
紧急修复先合入后补录，补录时哪些字段不能省？
补录可以简化流程，但工作项编号、提交号与合并请求、合入状态与时间这三类信息应当保留，它们分别支撑业务对应、代码事实和交付结果。变更说明写清修复了什么现象、影响范围，验证结论写清验证方式与执行人。补录记录中注明“事后补录”及原因，便于后续复盘时区分正常流程记录与补录记录。
记录放在工作项侧还是代码侧，团队内部意见不一致怎么办？
先确认主要使用者从哪一侧查记录：业务和测试人员通常从工作项出发查变更，开发人员通常从合并请求出发查业务意图。常见折中是两侧都放摘要，选定一侧作为主记录完整填写，另一侧只保留主记录编号与关键结论。选择依据是检索习惯和协作分工，团队约定后写入规范并保持稳定，比反复调整位置更重要。
所用平台的字段和示例对不上，是否需要完全照搬示例结构？
不需要逐字段照搬。示例给出的是信息类别，不同平台可能把提交号、分支、合并请求放在独立字段，也可能写在描述或备注中。套用前核对平台实际可用的字段与关联方式，保证编号、代码事实、验证证据、合入状态四类信息都有承载位置即可。字段名称和呈现形式可以按平台调整，信息完整性是判断标准。
