技术债务：如何度量、排优先级并逐步偿还

每个团队都在谈技术债务，但几乎没有团队能说清楚自己到底欠了多少、每个迭代要为此付出多少代价、或者应该先还哪笔债。这个词已经变成了"我不喜欢的代码"的代名词——既无法排优先级，也很容易被管理层忽视。本文用一套具体的系统替换这种模糊的抱怨：如何分类债务以便理解其本质，如何度量以便核算成本，如何排序以便做对的事情，以及如何呈现以便控制路线图的人真正批准这项工作。

发布于 2026-01-19 · ✓ 已更新 2026-05-06 · 阅读约 9 分钟 · 作者：Daniel Marsh · 审校：编辑政策

并非所有债务都一样

Ward Cunningham 最初的债务隐喻指的是：代码能工作，但尚未反映团队对问题的完整理解。这是有价值的债务——先发布、再学习、再重构。但这个概念后来被无限扩大，从缺少测试到意大利面条架构，再到没人清理的复制粘贴工具函数，什么都往里装。把所有这些当作同一类东西来对待，就无法做出合理的优先级判断。

更实用的分类方法使用两个维度：有意 vs. 无意 和 鲁莽 vs. 审慎。这产生了四个象限：

这个区分很重要，因为每个象限的修复策略不同。有意-审慎的债务通常已有工单。无意-鲁莽的债务通常需要架构层面的工作和专门的设计文档。不做区分就给债务贴标签，就像说"我们有健康问题"却不区分脚扭伤和心脏病。

Spec-first 实践对"无意"类别的影响最大。当团队跳过设计文档阶段——实现前没有书面设计——他们就无法区分有意的权衡和无意的疏忽。债务在没有人主动选择承担的情况下不断积累，也没有记录表明预期的设计应该是什么样的。

设计文档如何防止无意债务

无意债务是最隐蔽的类别，因为没有人决定承担它。当团队在没有共同理解的情况下开始编码时，它就出现了。三个工程师对同一个需求做出三种不同的解读，而不一致之处在任何人注意到之前就已经变成了承重结构。

Spec-first 工作流在成本最低的时刻拦截这个问题。当设计在实现开始前被写下、评审并达成一致时，团队在纸面上而不是在 Pull Request 中发现冲突的假设。具体来说：

• 接口边界被显式定义。两个服务不会各自演化出对谁拥有某个状态的不兼容假设——设计文档明确了所有者。当边界后来发生变化时，有一份文档可以更新——债务是可见的。
• 非目标防止范围蔓延。一半的无意债务来自工程师添加"既然在改这里"的功能，这些功能没有作为一个整体被设计、评审或测试。一份包含明确非目标的设计文档给团队提供了说"那是另一项独立工作"的参考依据。
• 错误路径是设计出来的，不是临场发挥的。当错误处理被留到实现阶段，每个工程师都会发明自己的重试逻辑、降级行为和日志格式。结果是代码库中不一致的错误处理——这笔债务在生产事故暴露它之前都是隐形的。
• 评审在早期发现结构问题。设计文档评审比代码评审更低成本地发现架构层面的偏差，因为你评审的是意图和结构，而不是数百行实现。

这不能消除有意债务——有时快速发布是正确的选择。但它确保了当你承担债务时，你知道自己在这样做、记录了原因，并且有一份设计文档描述了"偿还后"的版本应该是什么样子。

具体度量债务

无法量化的东西就无法排优先级。目标不是一个能捕捉所有债务的单一数字——那不存在。目标是一小组与债务实际对团队造成的成本相关的指标。以下是在实践中有效的指标：

按模块的变更失败率。追踪代码库中哪些区域在部署后产生最多的回退、热修复或回滚。如果支付模块的变更失败率是 25%，而系统其他部分是 5%，这是一个量化的信号——那里存在结构性问题。你的 CI/CD 管道和事故追踪器里已经有这些数据。

常见变更类型的修改时间。选择团队频繁做的五种变更类型——添加新 API 字段、修改业务规则、集成新的第三方服务。估算在一个干净的代码库中每种应该花多长时间，然后测量实际花了多长时间。差距就是你的债务对每个功能征收的税。如果因为紧耦合的数据层，添加一个 API 字段需要两天而不是两小时，那就是一个可以拿给干系人看的可度量成本。

事故关联。对过去六个月的每个生产事故，将根因标记为：缺少测试覆盖、接口契约不清晰、错误处理遗漏、扩展假设失效或配置复杂度。然后统计。如果"接口契约不清晰"出现在 40% 的事故中，那就明确告诉了你哪个类别的债务最昂贵。

代码级指标。圈复杂度、模块间耦合度、测试覆盖缺口和变更频率（文件被修改的频率）都提供有用的信号。单独来看，没有一个指标能证明债务存在。但结合上面的运维数据，它们帮你定位债务。一个高复杂度、高变更频率、低测试覆盖率，又恰好位于高变更失败率模块中的文件，几乎肯定承载着严重的债务。

债务度量看板 — 季度评审：

模块             | 变更失败率 | 平均修改时间   | 事故数 (6个月) | 覆盖率
-----------------+-----------+---------------+---------------+-------
payments         |      25%  |      3.2 天   |            7  |   42%
user-auth        |       8%  |      1.1 天   |            2  |   78%
notifications    |      18%  |      2.4 天   |            4  |   35%
search           |       4%  |      0.5 天   |            1  |   81%
billing-reports  |      12%  |      1.8 天   |            3  |   58%

这张表用一个下午就能从团队已有的数据中整理出来。它把"我们有很多技术债"替换成了"支付模块每次变更的成本是搜索模块的 3 倍，产生的事故是 7 倍。"

优先级矩阵

度量告诉你债务在哪里以及它的成本。优先级告诉你先修什么。并非所有债务都值得偿还——有些债务存在于很少变动的代码中，承载它的成本接近零。这个矩阵使用两个维度：

"立即修复"象限通常比团队预期的要小。大多数债务落在"排期"或"忽略"中。这是好事——意味着你的偿还工作是聚焦的、有据可依的、有限的。你不是在要求花一个季度重写系统。你是在要求用两个迭代修复那三个导致了 60% 事故的模块。

编写偿还设计文档

技术债务工作失败，往往是因为被当作了非结构化的重构时间。"我们要清理支付模块"不是一个计划——它是一个愿望。每个重大的债务偿还项都需要一份设计文档，就像功能开发一样。设计文档应包含：

• 当前状态：代码现在是什么样？具体痛点是什么？引用你的度量数据——变更失败率、事故数、修改时间基准。
• 目标状态：工作完成后代码应该是什么样？明确接口变化、抽象边界、测试覆盖目标。
• 迁移计划：如何在不影响生产的情况下从当前状态到达目标状态？能否在功能开关后面增量完成？如果重构引入回归，回滚计划是什么？
• 验收标准：如何判断工作完成？"代码更干净了"不是验收标准。"支付模块变更失败率降至 10% 以下"才是。
• 范围边界：这一轮故意不修什么？没有范围边界的债务偿还会膨胀直到吞掉整个迭代。

对"只是重构"来说这可能感觉像是额外负担。但它不是。设计文档是防止工作膨胀的东西，是让工作可评审的东西，是给你提供投资回报证据的东西。在我的经验中，每次失败的债务偿还都是因为没有书面的目标状态——团队只是开始重构，然后在时间用完时停下来，代码变成了不同但未必更好的状态。

向干系人争取债务偿还资源

工程师常常输掉这场争论，因为他们框架搭错了。"我们需要重构支付模块因为代码很糟糕"是一个工程观点。它可能是对的，但对管理产品路线图的人来说不具有行动力。以下是有效的做法：

用业务成本开头。"每个涉及支付模块的功能发布时间延长 3 倍，有 25% 的概率引发生产事故。过去两个季度，这大约花费了 14 个工程师-周和 3 次面向客户的中断。"这是产品经理可以与修复成本进行比较的数字。

提出有限度的投入。"我们不是要求重写。我们要求一名工程师用三个迭代，按照清晰的接口契约重组支付处理管线。这是设计文档。"一个有范围、附带设计文档的项目是一个可管理的投资。一个开放式的"修复技术债"请求是一个黑洞。

定义回报。"完成这项工作后，我们预计变更失败率从 25% 降到 10% 以下，支付相关功能的修改时间从 3.2 天降到 1 天以内。我们会在完成后的两个季度持续衡量。"可度量的成果把一个维护请求变成了有预期回报的投资。

展示不作为的代价。"如果不处理，Q3 路线图上每个涉及支付的功能都会承受同样的 3 倍额外开销。估计整个季度会多出 8 个工程师-周的拖累，再加上至少一次面向客户的事故的可能性。"比较的不是"修债务 vs. 做功能"——而是"全速做功能 vs. 以三分之一的速度做功能。"

将债务偿还内建到流程中

一次性的债务清理长期来看不起作用。团队偿还了最严重的欠账，感觉良好一个月，然后以同样的速率积累新债务——因为流程没有任何变化。可持续的债务管理需要结构性变革：

每迭代的债务预算。为每个迭代保留 15-20% 用于债务工作。不是模糊的分配——而是从你已排序的债务积压中拉出的、已有设计文档的具体工单。如果迭代有 40 点的产能，6-8 点分给已经有设计文档和优先级的债务项。这不可妥协。一旦债务工作变成"剩余时间做的事"，它永远不会发生。

回顾会中的债务复盘。每个季度一次，审查你的度量看板。你投入资源的模块，变更失败率改善了吗？有没有什么新的地方在恶化？这把债务管理变成一个反馈循环，而不是一次性事件。

Spec-first 作为预防手段。最便宜的债务是你从未承担的债务。在实现前要求设计文档——配合明确的评审清单——能在代码进入代码库之前捕获无意-鲁莽和无意-审慎两个类别的债务。有意债务仍然应该被允许，但应该在设计文档中记录为已知权衡，并附带计划的偿还日期。

在创建时标记债务。当团队承担有意债务时，设计文档应包含一个"债务"部分，命名权衡、原因和偿还触发条件。"由于事件总线尚未就绪，我们用轮询实现发布。当事件总线达到 GA 时迁移到事件驱动，预计 Q3。"这创建了一个可搜索的、带上下文的已知债务积压，而不是通常那种没人记得代码为什么是这个样子的局面。

良好状态是什么样

管理良好的团队不是零债务——那意味着他们在过度工程化，发布太慢。他们拥有的是可见性：他们知道债务在哪里、成本是什么、计划何时处理。具体来说：

• 他们能展示一个按模块划分的变更失败率、修改时间和事故关联看板——每季度更新。
• 他们有一个已排优先级、附带设计文档的债务积压，而不是一堆模糊的抱怨。
• 他们在每个迭代中分配固定比例给债务工作，并且能展示交付了什么。
• 他们的有意债务在原始设计文档中记录了到期日和触发条件。
• 他们的事故复盘包含一个"债务贡献"字段，追踪现有债务是否为促成因素。
• 他们的干系人用业务语言理解这种权衡——不是因为工程师抱怨代码质量，而是因为数据展示了成本。

这不需要新工具或专门的"平台团队"。它需要的是把债务当作一个工程管理问题来对待，像对待事故响应或容量规划一样严格：度量、排优先级、分配资源、复盘。做到这些的团队比做不到的团队发布更快——不是因为他们的债务更少，而是因为他们知道哪些债务重要，并且为此制定了计划。