技术债准入记录用于在债务进入待办前完成一次可评审的判断：这条债是什么、为什么产生、影响多大、偿还大概要多少成本、现在是否值得做。本文给出一份假设情景下已填写的完整样例，并逐项说明填写口径，帮助团队把口头讨论变成可追踪的记录。
要点总览（TL;DR）
- 技术债准入记录在债务进入待办前完成判断，核心字段包括债务描述、产生原因、影响范围、风险等级、偿还成本、准入结论、责任人与复审时间。
- 示例以支付回调逻辑职责过载为假设情景，演示描述具体化、影响与成本附依据、结论范围可控的填写方式。
- 准入结论建议采用准入、暂缓、拒绝、需补充信息等有限取值，并绑定责任人与具体复审节点，避免长期挂账。
- 记录可迁移到其他团队与债务类型，前提是保留描述具体化、结论可复核、单条范围可控三条规律，并与迭代评审、待办排序衔接。
- 已确认功能 Bug 归缺陷管理，重构代码方案在实施阶段展开，紧急线上临时处置与准入记录分开处理。
这份示例要解决什么准入判断
技术债准入记录的使用时机，通常是在团队识别到一处债务、准备把它放进待办列表之前。它要回答的核心问题是：这条债是否值得现在进入待办，以什么优先级进入，由谁负责，什么时候需要重新评估。记录的价值在于把判断依据固定下来，让后续的评审、排序和复盘有据可查，避免同一处债务反复被提起又反复被搁置。
本文示例为假设情景，用于演示填写方式，不代表任何真实客户案例，也不附带量化成效。示例假设一个约十人的产品研发团队，维护一套包含支付、订单、账户等模块的线上系统，采用两周一个迭代的节奏，技术债由研发人员在日常开发中提出，在迭代规划会上集中评审。
示例覆盖的债务类型是结构性技术债：支付模块中一段历史逻辑承担了过多职责，导致每次改动都需要额外验证。这类债务介于“明显影响交付速度”和“尚未引发故障”之间，正是准入判断最需要记录依据的场景。情景假设清单如下：
- 团队规模：约十人，前后端分工，无专职架构师。
- 系统状态：已上线运行，支付模块近半年改动频繁。
- 提出方式：研发人员在迭代中登记，规划会评审。
- 记录目的：决定是否进入待办、以什么顺序进入。
完整示例：一条支付模块技术债的准入记录
下面是一份字段齐全的准入记录。为便于阅读，用表格呈现字段与填写内容，实际使用时可以按团队习惯调整为文档或工作项字段。
| 字段 | 填写内容 |
|---|---|
| 记录编号 | TD-2024-017 |
| 债务名称 | 支付回调处理逻辑职责过载 |
| 债务描述 | 支付回调入口函数同时承担签名校验、订单状态更新、库存扣减通知、对账消息发送四类职责，单文件约八百行。新增一种支付渠道时，需要在该函数内增加分支，并回归全部已有渠道的回调路径。 |
| 产生原因 | 早期为赶支付渠道上线进度，将多渠道差异逻辑集中在一个入口快速实现；后续每次新增渠道沿用同一写法，未做拆分。 |
| 影响范围 | 支付模块回调链路；涉及订单状态与对账消息两个下游；近三个月该文件改动六次，每次改动平均需要回归三个渠道的回调场景。 |
| 风险等级 | 中。当前无已知线上故障，但改动频繁且回归范围大，一次遗漏可能造成订单状态与对账不一致。 |
| 偿还成本估算 | 约八至十二人天，含拆分职责、补充回调链路测试、分渠道灰度验证。估算依据为同类拆分工作的历史经验，未包含对账侧联调时间，存在上浮可能。 |
| 优先级 | 中高。下一次新增支付渠道前完成，避免继续叠加分支。 |
| 准入结论 | 准入。纳入下个迭代的技术债专项，先做职责拆分与测试补齐，渠道差异逻辑的进一步抽象另立记录。 |
| 责任人 | 支付模块负责人（研发），测试负责人配合回归方案。 |
| 复审时间 | 下个迭代规划会前，若期间新增渠道需求提前到来，立即复审。 |
| 关联工作项 | 主工作项 TD-2024-017，关联测试补齐子任务与灰度验证子任务。 |
| 记录状态 | 已准入，待排期。 |
这份记录的关键在于自洽：描述里提到“新增渠道需回归全部已有渠道”，影响范围就给出改动频次与回归范围，成本估算也把测试补齐和灰度验证算进去，准入结论则把“职责拆分”和“渠道差异抽象”拆成两件事，避免一次记录承载过大的范围。关联工作项与文档记录方式按团队工具而定，记录本身需要能被检索、能被关联到迭代。
逐项解释：每个字段为什么这样填
字段填写的共同标准是可判断、可复核：另一位没有参与讨论的同事读完记录，能大致得出相同的影响判断和成本量级。下面按字段说明口径，并给出会让记录失效的写法。
债务描述写到可判断的程度
描述要包含位置、现状和具体后果。示例写明了入口函数承担哪四类职责、文件规模、新增渠道时的具体动作。反例是“支付模块代码质量差，需要重构”，这类表述无法判断影响范围，也无法估算成本，评审时只能凭印象争论。另一个常见问题是描述里混入解决方案，比如直接写“应拆成四个服务”，这会把判断和方案绑死，压缩后续讨论空间。
影响范围与风险等级的判断依据
影响范围回答“改这里会牵动什么”，宜写清受影响模块、下游依赖、改动频次和回归范围。风险等级在此基础上叠加故障后果：当前是否已有故障、一旦出错的业务影响是什么。示例给“中”而不是“高”，依据是无已知线上故障但改动频繁、回归面大。风险等级需要有判断依据句，只写等级不写理由，复审时就无法判断等级是否仍然成立。
成本估算的口径与不确定性标注
成本估算要写明口径：是人天还是迭代数，包含哪些工作，不包含哪些工作。示例给出八至十二人天的区间，并注明未含对账侧联调，这种标注让后续排期时知道哪里可能超支。反例是只写“大概两周”，既没有口径也没有范围，评审无法比较不同债务之间的投入。区间估算通常比单一数字更有参考价值，尤其是涉及跨模块联调的工作。
准入结论的取值与含义
准入结论建议使用有限取值，便于统计和追踪。常见取值及含义如下：
- 准入：判断成立，进入待办并按优先级排期。
- 暂缓：判断成立但当前时机不合适，记录保留，到期复审。
- 拒绝：判断不成立，例如影响被高估或已有其他方式覆盖，记录关闭并写明理由。
- 需补充信息：描述、影响或成本不足以判断，退回提出人补充后再评审。
示例选择“准入”，同时把范围收窄到职责拆分与测试补齐，把渠道差异抽象另立记录。这种拆分让单条记录的偿还成本可控，也避免一条记录长期挂着无法关闭。
责任人与复审时间的设定理由
责任人应是能推动这条债务落地的人，通常是模块负责人，而不是提出人。复审时间要绑定一个具体节点，例如下个迭代规划会前，或某个需求上线前。示例把复审时间与“新增渠道需求”绑定，是因为这条债务的紧迫性正来自渠道叠加。没有复审时间的记录容易变成长期挂账，既不被关闭也不被推进。
从这份示例可以迁移的填写规律
这份示例可以迁移到其他团队和债务类型，前提是保留几条通用规律。第一，描述具体化：写清位置、现状、触发条件和后果，让判断有落点。第二，结论可复核：每个等级、每个估算都附依据句，复审时能判断依据是否变化。第三，范围可控：一条记录对应一件可完成的事，过大的债务拆成多条，分别准入。
接入日常流程时，准入记录需要与两个环节衔接。其一是迭代评审：在规划会上集中过一遍新登记和到期复审的记录，逐条给出结论，避免在开发过程中零散讨论。其二是待办排序：已准入的记录进入待办时，优先级依据记录中的影响范围与紧迫性排序，而不是按提出先后。记录状态随债务偿还推进更新，例如从“已准入，待排期”到“进行中”，偿还完成后关闭并注明实际投入与估算的差异，这些差异是后续估算的参考。
当团队使用工作项与文档承载这类记录时，可以把准入记录建成独立的工作项类型，字段对应上述表格，关联子任务与迭代。ONES 支持用工作项承载技术债记录、用文档沉淀评审结论，并把记录关联到迭代与需求，便于在规划会上直接查看状态与复审时间；具体字段配置需结合团队实际设定。
适用边界：哪些情况不放进这份记录
准入记录服务于债务是否进入待办的判断，有几类相邻工作不适合放进来。已确认的功能 Bug 归缺陷管理流程，按缺陷的严重程度和处理时限流转；把 Bug 写进技术债准入记录，会让两类工作的统计和优先级混在一起。具体重构代码方案也不在记录内展开，记录只承载判断与结论，方案设计属于实施阶段的工作。
紧急线上问题的临时处置与准入记录分开处理：临时处置以恢复服务为目标，事后如果发现根因属于技术债，再单独登记一条准入记录，写明临时处置留下的状态。此外，记录中依赖外部信息的字段需要随资料补充而复核，例如成本估算在方案设计完成后应更新，影响范围在新渠道接入后应重新确认，复审时间到期时也要核对依据是否仍然成立。
- 已确认功能 Bug：走缺陷管理，不写入准入记录。
- 重构代码方案：在实施阶段展开，记录只写结论与范围。
- 紧急线上临时处置：先恢复服务，事后按需单独登记。
- 依赖外部信息的字段：方案完成、渠道变化、复审到期时更新。
常见问题
技术债准入记录应该在什么时候登记，规划会上再补行不行？
登记时机宜在识别到债务、准备放入待办之前。规划会上集中评审是常见做法，但记录本身最好在会前完成初稿，否则评审容易变成现场回忆细节，影响范围和成本估算都难以写准。示例中的做法是研发人员在迭代中登记，规划会前由提出人补齐影响与成本字段，会上逐条给结论。
如果债务是在开发过程中临时发现的，可以先记一条简要记录，标注“需补充信息”，在下次评审前补全，避免口头提过就丢失。
成本估算只有提出人自己能说清，评审时其他人怎么判断是否合理？
关键在于估算要带口径和依据。写明是人天还是迭代数、包含哪些工作、不包含哪些工作，并注明估算依据，例如同类拆分工作的历史经验。示例给出八至十二人天的区间，并注明未含对账侧联调，评审者即使不熟悉细节，也能判断量级和风险点。
如果团队有历史偿还记录，可以对照实际投入与估算的差异，逐步校准估算习惯。没有历史数据时，区间估算加不确定性标注比单一数字更稳妥。
一条技术债范围很大，拆成多条记录后优先级怎么排？
拆分后每条记录独立准入、独立排期，优先级依据各自的影响范围与紧迫性判断，而不是按原债务的整体印象排序。示例把“职责拆分与测试补齐”作为一条准入记录，把“渠道差异逻辑抽象”另立记录，前者在下一次新增渠道前完成，后者按后续需求节奏安排。
拆分时注意每条记录对应一件可完成的事，避免拆得过细导致记录数量膨胀、评审成本上升。可以在主记录中注明关联的子记录，保持追溯关系。
准入结论为“暂缓”的记录，复审时应该重点看什么？
复审时先核对当初暂缓的依据是否仍然成立，例如时机不合适是因为排期已满，还是因为影响被判断为可控。再看影响范围是否变化，比如改动频次上升、新增了下游依赖，这些变化可能让优先级上升。
如果依据没有变化，可以继续暂缓并更新复审时间；如果依据已经变化，应重新给出结论。复审记录本身也值得保留，便于后续判断这条债务被搁置了多久、原因是什么。
团队规模很小，也需要维护完整的准入记录吗？
记录的价值在于让判断可复核、可追踪，与团队规模没有直接关系。小团队可以简化字段，例如合并影响范围与风险等级、省略部分关联信息，但债务描述、准入结论、责任人与复审时间这几项建议保留，否则债务容易停留在口头讨论。
简化时注意保留判断依据句，等级和估算都附上理由，这样即使换人接手，也能理解当初为什么这样判断。字段数量可以少，判断链条不宜断。
