技术债准入记录要回答三个问题：这笔债该不该进、由谁批准、什么时候还。建议按“识别—评估—准入决策—偿还跟踪—关闭复盘”五段保留信息，核心字段包括编号、所属系统与模块、债务来源与类型、影响与风险、修复成本与利息估算、准入结论与决策人、偿还负责人与验收标准，以及状态变更和关闭证据。下面给出一份可直接复制的空白表格，并说明每个字段怎么填、哪些必填、如何随团队变化调整。
要点总览（TL;DR）
- 技术债准入记录按“识别—评估—准入决策—偿还跟踪—关闭复盘”五段保留信息，核心是让每条债务可追溯、可决策、可复盘。
- 必填字段围绕决策与责任设置：编号、标题、所属系统与模块、来源与类型、影响与风险、修复成本、优先级、准入结论与决策人、偿还负责人、验收标准、当前状态。
- 利息估算、准入条件、偿还期限、状态变更记录、关闭证据与复盘结论可作为选填，按团队规模与系统耦合程度逐步转为必填。
- 模板应保留版本号与变更记录，字段增删需经评审并同步更新字段说明，旧记录不追溯改写。
- 准入记录与缺陷管理、需求管理保持边界：已确认功能 Bug 走缺陷流程，债务排期引用需求管理中的版本号。
可复制空白模板：技术债准入记录表
下表按五段信息结构组织，可直接复制到文档工具或表格工具中使用。表头字段清单即字段全集，团队可按后文“必填与选填”裁剪，但建议保留五段的段落划分，便于评审时按顺序阅读。
| 段落 | 字段 | 填写内容 |
|---|---|---|
| 基础标识 | 债务编号 | |
| 债务标题 | ||
| 所属系统 / 模块 | ||
| 提出人 / 提出日期 | ||
| 债务来源 | ||
| 债务类型 | ||
| 评估 | 影响范围 | |
| 风险描述 | ||
| 修复成本估算 | ||
| 利息估算 | ||
| 优先级建议 | ||
| 准入决策 | 是否准入 | |
| 决策人 / 决策日期 | ||
| 准入条件 | ||
| 偿还期限 | ||
| 决策依据摘要 | ||
| 偿还跟踪 | 目标版本 / 迭代 | |
| 偿还负责人 | ||
| 验收标准 | ||
| 当前状态 | ||
| 状态变更记录 | ||
| 关闭复盘 | 关闭日期 | |
| 关闭证据 | ||
| 实际成本与偏差 | ||
| 复盘结论 |
表格之外建议保留两个附属信息：模板版本号与变更记录。它们不针对单条债务，而用于管理模板本身，具体做法见最后一节。
字段说明：每个字段记录什么、怎么填
字段说明的目标是让不同的人填出可比较的记录。以下逐项解释含义与填写口径，示例取值仅示意格式，不代表真实项目数据。
| 字段 | 记录什么 | 填写口径与示例 |
|---|---|---|
| 债务编号 | 唯一标识 | 采用“系统缩写-年份-序号”，如 PAY-2025-014，便于跨文档引用 |
| 债务标题 | 一句话说明债务 | 写清对象与问题，如“支付回调模块缺少幂等校验”，避免只写“代码烂” |
| 所属系统 / 模块 | 定位范围 | 写到可负责的粒度，如“支付服务 / 回调处理” |
| 提出人 / 提出日期 | 追溯来源 | 填写实际提出者与首次记录日期，便于后续追问背景 |
| 债务来源 | 债务怎么产生的 | 可选：历史遗留、赶工期妥协、技术选型过时、需求变更累积、外部依赖升级 |
| 债务类型 | 债务性质分类 | 可选：代码结构、架构设计、测试缺失、文档缺失、依赖版本、性能隐患 |
| 影响范围 | 波及的业务与系统 | 写受影响的业务功能、调用方数量或团队，如“影响 3 个下游服务” |
| 风险描述 | 不处理的后果 | 写可观察的风险，如“高峰期重复扣款概率上升”“新人上手需额外两天” |
| 修复成本估算 | 偿还所需投入 | 用人天或故事点，注明估算依据，如“约 5 人天，含回归测试” |
| 利息估算 | 拖延的持续代价 | 写每次迭代或每月额外消耗，如“每迭代约 0.5 人天排查同类问题” |
| 优先级建议 | 排序参考 | 高 / 中 / 低，并附一句理由，如“高：涉及资金准确性” |
| 是否准入 | 决策结论 | 准入 / 有条件准入 / 不准入，三选一，避免留空 |
| 决策人 / 决策日期 | 责任归属 | 填写实际拍板人，而非会议记录人 |
| 准入条件 | 准入的前提 | 如“须在下个版本前补充监控告警”，无条件则填“无” |
| 偿还期限 | 时间约束 | 写版本号或日期，如“2025 Q3 内” |
| 决策依据摘要 | 结论的理由 | 两三句话概括成本、风险与业务节奏的权衡 |
| 目标版本 / 迭代 | 排期落点 | 与需求管理中的版本号保持一致 |
| 偿还负责人 | 执行责任 | 填具体个人，不填团队名 |
| 验收标准 | 完成的判定 | 可核验，如“重复回调测试用例全部通过，线上重复扣款告警归零” |
| 当前状态 | 跟踪状态 | 待评估 / 已准入待排期 / 偿还中 / 已关闭 / 已拒绝 |
| 状态变更记录 | 流转留痕 | 记录每次状态变化的时间与操作人 |
| 关闭日期 | 结束时间 | 验收通过当天填写 |
| 关闭证据 | 完成凭据 | 测试报告、发布记录或评审结论的引用位置 |
| 实际成本与偏差 | 估算校准 | 如“实际 7 人天，超估 2 人天，因兼容旧接口” |
| 复盘结论 | 经验沉淀 | 一句话说明下次如何避免或更准估算 |
容易混淆的是“修复成本估算”和“利息估算”：前者是偿还一次投入多少，后者是继续拖延每期损失多少。两者分开记录，才能比较“现在修”和“晚点修”的差别。“债务来源”与“债务类型”也常被混填，来源回答怎么产生的，类型回答属于哪类问题，一条记录可以同时有多个类型。
必填与选填：哪些字段决定记录能否用于决策
划分依据只有一条：缺少该字段，是否会导致无法判断准入结论或无法追踪偿还责任。满足这条的进必填，其余作为选填，用于复盘与度量。
| 类别 | 字段 | 理由 |
|---|---|---|
| 必填 | 债务编号、债务标题、所属系统 / 模块、提出人、提出日期 | 保证记录可被唯一引用和追溯 |
| 必填 | 债务来源、债务类型 | 决定后续分类统计与责任归属 |
| 必填 | 影响范围、风险描述 | 没有影响与风险，准入决策缺少依据 |
| 必填 | 修复成本估算、优先级建议 | 成本与排序是决策的直接输入 |
| 必填 | 是否准入、决策人、决策日期 | 准入记录的核心结论与责任 |
| 必填 | 偿还负责人、验收标准、当前状态 | 保证准入后有执行人和完成判定 |
| 选填 | 利息估算 | 有助于比较拖延代价，但初期团队可能缺少数据 |
| 选填 | 准入条件、偿还期限、决策依据摘要 | 有条件准入或争议较大时补充，简单记录可省略 |
| 选填 | 目标版本 / 迭代、状态变更记录 | 排期确定后补充；状态记录可由工具自动留痕 |
| 选填 | 关闭日期、关闭证据、实际成本与偏差、复盘结论 | 关闭阶段填写，用于校准估算和沉淀经验 |
按团队规模裁剪时，小团队（十人以内）可先保留必填字段，把利息估算和复盘结论放到季度回顾时统一补；跨团队协作或系统耦合较深时，建议把利息估算和状态变更记录转为必填，因为拖延代价和交接责任更容易被忽略。裁剪的原则是减字段不减段落：即使某段只留一个字段，也保留段落标题，评审时仍能按“识别—评估—决策—跟踪—关闭”的顺序检查。
填写示例：一条完整的技术债准入记录
以下为演示情景，用于说明各字段如何配合，数据为示意值。
| 字段 | 填写内容 |
|---|---|
| 债务编号 | PAY-2025-014 |
| 债务标题 | 支付回调模块缺少幂等校验 |
| 所属系统 / 模块 | 支付服务 / 回调处理 |
| 提出人 / 提出日期 | 李工 / 2025-04-08 |
| 债务来源 | 赶工期妥协 |
| 债务类型 | 代码结构、测试缺失 |
| 影响范围 | 支付回调链路，涉及 3 个下游服务 |
| 风险描述 | 第三方重复推送时可能重复入账，高峰期概率上升；缺少对应测试用例 |
| 修复成本估算 | 约 5 人天，含幂等键设计与回归测试 |
| 利息估算 | 每迭代约 0.5 人天用于排查重复入账工单 |
| 优先级建议 | 高：涉及资金准确性 |
| 是否准入 | 有条件准入 |
| 决策人 / 决策日期 | 王架构师 / 2025-04-12 |
| 准入条件 | 先补充重复回调监控告警，再进入排期 |
| 偿还期限 | 2025 Q3 内 |
| 决策依据摘要 | 资金风险高但当前版本排期满，先加监控降低暴露面，下季度集中偿还 |
| 目标版本 / 迭代 | V3.8 |
| 偿还负责人 | 张工 |
| 验收标准 | 重复回调测试用例全部通过，线上重复入账告警连续两周为零 |
| 当前状态 | 已准入待排期 |
| 状态变更记录 | 2025-04-08 提出；2025-04-12 准入决策 |
| 关闭日期 | （待填） |
| 关闭证据 | （待填） |
| 实际成本与偏差 | （待填） |
| 复盘结论 | （待填） |
这条记录的关键在于“有条件准入”的处理：决策结论不是简单的准入或拒绝，而是附带监控前置条件，并把偿还期限与目标版本绑定。验收标准写成可核验的告警指标，而不是“完成幂等改造”这类模糊表述，关闭时才有据可查。关闭段留空是正常状态，表示债务尚未偿还完毕。
当这类记录需要多人协作填写和评审时，可以把模板放在文档空间统一维护，让每条债务记录与对应的项目任务关联。ONES Wiki 支持页面组关联项目、文档关联项目任务，准入记录与偿还任务可以互相对应；页面模板库可用于一键创建制式化文档，版本记录支持查看与回滚，便于模板和记录留痕。具体模板类型与权限粒度需按团队实际配置核验。
调整与维护方法：让准入记录长期可用
模板的价值在于稳定可比，因此调整要有触发条件和评审节奏，避免每个人按自己习惯改字段。
字段增删的常见触发条件包括：连续多个季度出现同类债务反复准入却无法关闭，说明缺少约束字段；评审会上反复口头补充同一类信息，说明该信息应转为字段；度量报表需要的维度在记录中找不到来源。出现这些信号时提出字段变更，而不是临时在记录里加备注。
版本与变更记录建议在模板文档顶部保留：模板版本号、变更日期、变更人、变更内容与影响范围。字段增删时同步更新字段说明表，旧记录不追溯改写，必要时在旧记录中标注适用的模板版本，保证历史数据可解释。
维护责任人建议由技术债治理的牵头角色担任，例如架构师或研发效能负责人，负责收集填写问题、组织评审。评审节奏可与季度技术债回顾合并，每次评审确认三件事：字段是否仍支撑决策、必填项是否被普遍跳过、关闭段的证据是否齐全。
与缺陷管理、需求管理的边界要在模板中写清：已确认的功能 Bug 走缺陷流程，按缺陷的严重程度和修复流程处理；技术债准入记录只承载债务的识别、准入决策与偿还跟踪。与需求管理的衔接点在“目标版本 / 迭代”字段，债务排期引用需求管理中的版本号即可，不重复维护一套排期。边界写进模板说明，能减少同一问题在两套流程中重复登记。
常见问题
技术债准入记录和缺陷记录、需求记录怎么区分，避免同一问题重复登记？
按问题性质分流入不同流程：已确认的功能 Bug 进入缺陷管理，按缺陷的严重程度和修复流程处理；有明确业务价值的新增能力进入需求管理；技术债准入记录只承载债务的识别、准入决策与偿还跟踪。
衔接点放在“目标版本 / 迭代”字段，债务排期引用需求管理中的版本号，不重复维护一套排期。边界写进模板说明，评审时按性质判断归属，能减少同一问题在两套流程中重复登记。
团队刚开始建准入记录，字段填不全怎么办？
先保证必填字段完整，尤其是准入结论、决策人、偿还负责人和验收标准这四项，它们决定记录能否用于决策和追踪。利息估算、实际成本与偏差等字段初期缺少数据时可以留空，在季度回顾时统一补充。
裁剪的原则是减字段不减段落：即使某段只留一个字段，也保留段落标题，评审时仍能按“识别—评估—决策—跟踪—关闭”的顺序检查，后续补字段时结构不用重排。
有条件准入的记录，关闭时以什么为准？
以准入时写下的验收标准为准，同时核对准入条件是否已经落实。例如准入条件是“先补充重复回调监控告警”，关闭时既要确认告警已上线，也要确认验收标准中的测试用例通过、告警指标归零。
如果偿还过程中验收标准需要调整，应在状态变更记录中写明调整时间、调整人和理由，保持关闭证据与最终验收标准一致，避免关闭时出现口径争议。
准入记录放在文档里还是工作项里更合适？
两种承载方式各有适用场景：以文档承载便于完整填写字段、保留决策依据摘要和复盘结论，适合评审与归档；以工作项承载便于排期、指派负责人和跟踪状态流转，适合偿还执行阶段。
常见做法是文档保存完整记录，工作项关联对应的偿还任务，两边通过编号互相引用。ONES Wiki 支持页面组关联项目、文档关联项目任务，页面模板库可用于一键创建制式化文档，版本记录支持查看与回滚，便于模板和记录留痕；具体模板类型与权限粒度需按团队实际配置核验。
模板运行一段时间后，怎么判断该加字段还是该减字段？
看两个信号：一是评审会上反复口头补充同一类信息，说明该信息应转为字段；二是度量报表需要的维度在记录中找不到来源，说明字段覆盖不足。反过来，如果某个字段连续多个季度无人填写、也不影响任何决策，可以考虑降为选填或删除。
字段变更走评审并记录在模板变更记录中，同步更新字段说明表。旧记录不追溯改写，必要时标注适用的模板版本，保证历史数据仍可解释。
