技术债台账要回答的是“这笔债在哪里、为什么欠、影响多大、准备怎么还、谁来推进、何时关闭”。一张可用的台账通常包含八类信息：债务标识、位置范围、类型与成因、影响与风险、偿还方案与成本、优先级与排期、责任人与状态、验证与关闭依据。下面给出一张可直接复制到表格工具的空白模板，并逐字段说明填写口径、必填与选填的划分，再用一条完整记录示范，最后给出长期维护规则。模板适用于研发团队自建技术债清单，字段可按团队成熟度分阶段启用。
要点总览（TL;DR）
- 技术债台账按“识别—评估—处置—关闭”的决策链条组织字段，一行记录一笔债务，核心是让每笔债务可排序、可追责、可关闭。
- 必填字段覆盖编号、标题、系统/模块、类型、风险等级、偿还方案、优先级、负责人、状态，以及关闭时填写的验证方式与关闭依据；量化依据、成本、时间窗等可后补。
- 字段取值统一用固定枚举，量化依据给数字、时间范围和统计口径，标题写问题不写方案，关闭依据要附可追溯证据。
- 按团队成熟度分阶段启用字段：先跑核心必填项，再补成本与排期，最后把量化依据纳入必填，避免一次要求过全导致记录骤减。
- 台账需固定评审节奏与状态流转规则，已确认的功能 Bug 走缺陷管理，需求变更走需求管理，台账只收持续产生维护成本或风险的问题。
可复制空白技术债台账模板
先给结构。下表一行记录一笔债务，列顺序按“识别—评估—处置—关闭”的决策链条排列，便于从左到右阅读和排序。将表头复制到 Excel、在线表格或文档表格中即可使用，单元格保持空白，填写时参照下一节的字段说明。
| 序号 | 债务编号 | 债务标题 | 发现来源 | 系统/模块 | 代码位置或范围 | 债务类型 | 成因 | 影响面 | 风险等级 | 量化依据 | 偿还方案 | 预估成本 | 优先级 | 目标版本或时间窗 | 负责人 | 状态 | 评审记录 | 验证方式 | 关闭依据 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
使用方式有三条约定。第一，一行一笔债务，同一处代码存在多个独立问题时分行记录，避免一条记录里塞进多个偿还动作。第二，债务编号一经分配不再复用，删除记录时保留编号并标注作废，防止历史引用断链。第三，台账只登记“已知的、需要排期决策的”技术债；已确认的功能 Bug 走缺陷管理流程，不进入本表，否则台账会被日常缺陷淹没，失去治理价值。
每个字段记录什么、怎么填
字段说明按下表执行。取值口径由团队统一，同一列内保持同一种写法，例如风险等级统一用“高/中/低”，成本统一用人天。常见填错集中在三处：标题写成解决方案而非问题、影响面写成主观感受、关闭依据写成“已改完”。
| 字段名 | 含义 | 取值示例 | 填写要点 |
|---|---|---|---|
| 债务编号 | 台账内唯一标识 | TD-2024-017 | 按“前缀-年份-流水号”生成，不复用 |
| 债务标题 | 一句话描述债务本身 | 订单服务仍使用同步调用库存接口 | 写问题不写方案，控制在30字内 |
| 发现来源 | 债务被识别出的渠道 | 代码评审 / 线上故障复盘 / 架构评估 | 固定枚举值，便于统计来源分布 |
| 系统/模块 | 债务所属业务或技术单元 | 交易域-订单服务 | 与团队现有的系统清单命名一致 |
| 代码位置或范围 | 可定位到代码或配置的位置 | order-service/src/main/…/StockClient.java | 给仓库路径、类名或接口名，范围大时写清边界 |
| 债务类型 | 债务的性质分类 | 架构债 / 代码债 / 测试债 / 文档债 / 依赖债 | 用固定枚举，一类一值，不叠加多个标签 |
| 成因 | 债务产生的直接原因 | 为赶大促上线临时直连，未做异步改造 | 写事实经过，便于判断是否同类问题复发 |
| 影响面 | 债务波及的功能、团队或链路 | 影响下单主链路，涉及订单、库存两个团队 | 写可核对的对象，不写“影响较大” |
| 风险等级 | 综合影响与发生概率的等级 | 高 / 中 / 低 | 与量化依据配套，等级变化时同步更新依据 |
| 量化依据 | 支撑风险判断的数据 | 近3个月该接口超时告警12次，平均恢复25分钟 | 给数字、时间范围和统计口径 |
| 偿还方案 | 计划采取的处理动作 | 改为消息队列异步扣减，补充幂等校验 | 写到可执行的动作粒度，不写“重构一下” |
| 预估成本 | 完成偿还所需投入 | 8人天（含联调与回归） | 注明是否含测试与发布，口径全表统一 |
| 优先级 | 排期先后顺序 | P1 / P2 / P3 | 由风险等级与成本共同决定，规则写进团队约定 |
| 目标版本或时间窗 | 计划偿还的时间点 | v3.8 或 2024 Q3 | 未排期时留空并标注“待排期” |
| 负责人 | 推进偿还的责任人 | 张工（订单服务Owner） | 写具体个人，不写团队名 |
| 状态 | 债务当前所处阶段 | 待评估 / 已排期 / 处理中 / 待验证 / 已关闭 / 暂缓 | 固定枚举，流转规则见维护章节 |
| 评审记录 | 决策过程留痕 | 2024-06-12 架构评审通过，纳入Q3 | 记录日期、结论与参与角色 |
| 验证方式 | 确认债务已消除的手段 | 压测报告 + 告警观察两周 | 写可执行的检查动作，不写“看情况” |
| 关闭依据 | 关闭时附上的证据 | 压测通过链接、告警归零截图、代码合并记录 | 证据可追溯，缺证据不关闭 |
分类字段建议使用下拉枚举而非自由文本，否则统计时会出现“架构债”“架构类”“架构问题”并存的情况，无法汇总。量化依据是台账里最容易被省略、也最能提升决策质量的一列：没有数据时宁可写“暂无量化数据，按经验评估”，也不要编造数字。
必填与选填怎么划分
划分标准只有一条：缺少该字段会导致这笔债务无法排序、无法追责或无法关闭，就设为必填。按此标准，必填字段覆盖“能认出来、能排进去、有人负责、能验证关闭”四个环节，其余字段用于补充量化依据和关联信息，可后补。
| 类别 | 字段 | 理由 |
|---|---|---|
| 必填 | 债务编号、债务标题、系统/模块、债务类型、风险等级、偿还方案、优先级、负责人、状态 | 保证记录唯一可识别、可排序、可追责、可流转 |
| 必填 | 验证方式、关闭依据 | 关闭时填写，保证债务真正消除而非口头结案 |
| 选填 | 发现来源、代码位置或范围、成因、影响面、量化依据 | 提升判断质量，缺失时不影响基本流转 |
| 选填 | 预估成本、目标版本或时间窗、评审记录 | 排期阶段补齐，早期可留空 |
按团队成熟度分阶段启用更现实。起步阶段只强制必填中的核心九项，先让台账跑起来；运行一到两个迭代后，要求排期时补齐预估成本与目标版本；稳定运行后，再把量化依据纳入必填，用于支撑风险等级判断。一次性要求全部字段填满，通常的结果是记录数量骤减或字段被随意填写。
选填字段缺失时统一留空，并在状态或备注中标注“待补”，不要用“无”“暂无”“不清楚”混填，否则后续无法区分“确实没有”和“还没填”。评审时把待补字段作为检查项，排期前补齐即可。
一份完整填写示例
下面这条记录覆盖全部必填字段，并补齐了主要选填字段，可用于核对字段之间的对应关系。
| 字段 | 填写内容 |
|---|---|
| 债务编号 | TD-2024-017 |
| 债务标题 | 订单服务同步调用库存接口，大促期间超时导致下单失败 |
| 发现来源 | 线上故障复盘 |
| 系统/模块 | 交易域-订单服务 |
| 代码位置或范围 | order-service 中 StockClient 同步调用及下单主流程 |
| 债务类型 | 架构债 |
| 成因 | 大促前为赶上线临时改为同步直连，异步改造未排入计划 |
| 影响面 | 下单主链路，涉及订单、库存两个团队 |
| 风险等级 | 高 |
| 量化依据 | 近3个月该接口超时告警12次，平均恢复25分钟，影响订单约日均0.3% |
| 偿还方案 | 改为消息队列异步扣减库存，补充幂等与补偿校验 |
| 预估成本 | 8人天（含联调与回归测试） |
| 优先级 | P1 |
| 目标版本或时间窗 | v3.8（2024 Q3） |
| 负责人 | 张工（订单服务Owner） |
| 状态 | 已排期 |
| 评审记录 | 2024-06-12 架构评审通过，纳入Q3迭代 |
| 验证方式 | 大促压测报告 + 上线后两周告警观察 |
| 关闭依据 | 压测通过记录、告警归零截图、代码合并记录 |
这条示例的判断依据可以拆开看。风险等级定为“高”，依据是量化依据中的告警频次、恢复时长和订单影响比例三项数据同时指向主链路；预估成本8人天包含联调与回归，与全表“成本含测试发布”的口径一致；优先级P1来自“高风险 + 影响主链路 + 成本可控”的组合，而不是单看风险等级。若团队约定“高风险且成本超过20人天先拆分再排期”，这条记录因成本在阈值内可直接排期。
核对一致性时检查三点：示例中出现的每个必填字段都能在字段说明表中找到对应行；状态取值属于约定的枚举范围；关闭依据与验证方式描述的是同一组证据。三点都对上，说明模板、说明与示例三者一致，可以交付使用。
台账的调整与维护方法
台账建好后最常见的失效方式是“建表时热闹、三个月后无人更新”。维持长期可用需要固定评审节奏、明确更新责任，并对字段本身做版本管理。
评审节奏建议与团队现有例会合并，不单独增加会议。每两周或每个迭代在排期会上过一遍新增债务与状态变化，参与角色包括技术负责人、各模块负责人和产品经理；每季度做一次全量复盘，重点看长期“暂缓”的记录是否应关闭或升级。状态流转按“待评估→已排期→处理中→待验证→已关闭”推进，暂缓状态需注明原因和复查时间。更新责任落在负责人身上：状态变化由负责人当天更新，评审结论由主持人补充到评审记录。
字段增删遵循三条原则：新增字段先以选填试运行一个季度，确有使用再转必填；删除字段前确认历史数据已归档，避免统计口径断裂；每次调整在台账首页记录版本号、调整内容和生效日期，例如“v1.2 新增量化依据为必填，2024-07-01 生效”。关闭与归档方面，债务关闭必须附关闭依据，缺证据的记录退回“待验证”；已关闭记录保留在原表中并标记关闭日期，超过一年的关闭记录可移入归档表，主表只保留未关闭和近一年关闭的记录，保证日常查看不被历史数据干扰。
边界要写清楚：已确认的功能 Bug 进入缺陷管理流程，按缺陷的严重程度和修复节奏处理；技术债台账只收那些“当前能运行、但持续产生维护成本或风险”的问题，例如架构耦合、测试缺失、依赖过期、文档滞后。需求变更带来的新增开发工作走需求管理，也不进本台账。三类记录各走各的流程，台账才能保持“治理清单”的定位。
当团队希望把台账从个人表格升级为可协作的治理载体时，可以把台账文档与项目工作项放在同一套协作环境里。ONES Wiki 支持文档关联项目任务，页面树可以按系统或模块组织台账页面；页面模板库可用于固化台账表头，减少每次新建时的字段遗漏；文档实时同步并记录页面版本，支持查看与回滚，字段调整的历史可追溯；成员可以在线添加注释、评论，评审结论直接留在记录旁；读写权限可按角色配置，让模块负责人维护各自部分。这样台账的填写、评审和状态更新在同一处完成，减少表格在多人和多版本之间来回传递造成的口径不一致。
常见问题
技术债台账和缺陷管理清单有什么区别，什么该记在哪边？
判断标准是问题当前是否影响正常使用。已确认的功能 Bug 属于“现在就不能正常工作”，进入缺陷管理流程，按缺陷的严重程度和修复节奏处理；技术债是“当前能运行，但持续产生维护成本或风险”的问题，例如架构耦合、测试缺失、依赖过期、文档滞后，进入技术债台账。需求变更带来的新增开发工作走需求管理。三类记录分开，台账才不会被日常缺陷淹没。
团队刚开始建台账，字段填不全怎么办？
先只强制核心必填项，让台账跑起来，运行一到两个迭代后再逐步加码：排期时要求补齐预估成本与目标版本，稳定运行后再把量化依据纳入必填。选填字段缺失时统一留空并标注“待补”，不要用“无”“暂无”混填，否则后续无法区分“确实没有”和“还没填”。评审时把待补字段作为检查项，排期前补齐即可。
风险等级和优先级怎么定，才能避免全表都是“高”？
风险等级要有量化依据配套，例如告警频次、恢复时长、受影响的业务比例，等级变化时同步更新依据。优先级由风险等级与成本共同决定，而不是单看风险等级；团队可以把规则写进约定，例如“高风险且影响主链路、成本在阈值内直接排期，超过阈值先拆分再排期”。规则明确后，评审时按规则核对，主观判断的空间会小很多。
债务关闭后记录要不要从台账里删掉？
不删除。已关闭记录保留在原表中并标记关闭日期，超过一年的关闭记录可移入归档表，主表只保留未关闭和近一年关闭的记录。债务编号一经分配不再复用，删除记录时保留编号并标注作废，防止历史引用断链。关闭必须附关闭依据，缺证据的记录退回“待验证”。
台账放在在线表格里够用吗，什么时候需要换到协作平台？
单人或小团队用在线表格即可起步。当台账需要多人分模块维护、评审结论要留痕、字段调整要可追溯时，表格在多人和多版本之间传递容易造成口径不一致。此时可以把台账文档与项目工作项放在同一套协作环境里，例如 ONES Wiki 支持文档关联项目任务、页面模板库固化表头、页面版本记录与回滚、按角色配置读写权限，填写、评审和状态更新可在同一处完成。
