技术债务

是什么，为什么存在

技术债务（technical debt） 是一项设计或构造选择，它使未来某类软件变更比采用更合适的方案成本更高。成本可能表现为额外开发时间、更大的回归范围、更难验证的发布，或者更高的故障风险。只有当你能说清楚「哪类未来变化会因此更难」时，这个标签才有决策价值。

债务比喻把两种成本分开。 债务本金（debt principal） 是从当前状态迁移到选定目标状态所需的工作； 债务利息（debt interest） 是在债务仍存在时，每次触及相关区域多付出的工作或风险。与金融债务不同，软件债务通常不会仅因时间流逝而持续计息；一个从不再变化的旧模块可能很丑，却几乎不产生利息。

缺陷、缺少功能和技术债务彼此相关，但并不相同。一次计算错误需要修复，因为当前行为已经不正确；一段重复代码只有在后续变更必须同步修改多个副本时才产生债务利息；一个尚未实现的报表则是产品待办，不应伪装成债务。把所有不满意之处都放进债务清单，会让清单失去优先级。

有些债务是有意承担的，例如为了在确定的期限内交付，暂时让两个模块直接耦合。这个决定只有在短期收益、影响范围、负责人和退出触发条件都明确时才可控。另一类债务来自学习：团队交付后才发现领域边界与最初假设不同，即使当时的实现并不草率，也可能形成无意债务。

「有意」不等于「审慎」。一个已记录但没有安全边界、退出路径或足够测试的捷径，仍然可能是鲁莽的。反过来，无意债务也不表示团队失职；软件开发会揭示先前不知道的约束，关键是发现后如何处理。

你会在频繁共同修改的模块、跨层依赖、脆弱测试、缓慢构建、过期依赖、手工发布步骤和知识孤岛中遇到技术债务。这些只是候选信号，不是自动结论。静态分析能指出复杂度或循环依赖，却不能单独说明该区域未来会变多少次、失败后有什么业务影响。

技术债务管理的目标不是把代码库清理到抽象意义上的完美。目标是让团队知道自己承担了哪些未来成本，在成本妨碍交付或安全之前采取行动，并允许低利息债务在证据支持下继续存在。一个诚实的「暂不偿还」决定，比没有上下文的高优先级标签更有用。

工作原理

技术债务从一个可检验的假设开始：「因为当前结构，某类变更会额外花费什么？」团队先收集触发该判断的证据，再描述目标状态和迁移范围。只有这样，本金估算与利息观察才指向同一个问题。

一项债务通常经历五个阶段：发现候选项、用证据确认、接受或安排、实施修复、验证后退出。发现并不自动等于承诺重构；先确认影响，可以避免把偏好争论包装成紧急工作。退出也不等于合并了一个重构提交，必须证明目标状态已经实现且外部行为仍满足要求。

一条可执行的债务记录至少要保存以下内容。它不是重构愿望，而是连接问题、决策和验证的工作对象。

证据应尽量靠近真实变化。版本历史可以展示共同修改和热点，持续集成可以展示构建与测试等待时间，事故记录可以连接故障与结构原因，开发者可以在完成工作后记录实际绕行步骤。代码覆盖率和复杂度适合作为调查入口，但它们不能替代影响证据。

排序时先处理安全漏洞、数据损坏或正在发生的事故等不可接受风险。其余项目比较未来变化频率、每次变化的观察利息、影响半径、本金和不确定性。不要把这些维度过早压成一个带小数的总分；并列展示原始证据，决策者才能看见某个权重改变后结论是否会翻转。

合理的处理结果不止「立即修复」一种：

1. 立即阻断并修复当前风险，同时为后续结构修复建立独立范围。
2. 在下一次相关功能变更中增量偿还，因为那时既有上下文也有测试预算。
3. 明确接受债务，并设置日期、使用量、事故或依赖版本等复查触发条件。
4. 关闭误报，因为证据表明它是缺陷、产品待办、个人偏好，或者不再会变化的代码。

偿还工作要从可观察行为和边界开始，而不是从大规模改名开始。先用测试固定仍需保留的行为，再建立可以逐步替换的接缝，最后用目标状态对应的证据退出。对于跨系统迁移，可以结合特性开关或绞杀者模式，但迁移机制本身也必须有删除条件，否则它会成为下一笔债务。

示例

下面三个示例使用 Node 24 的内置 API。示例中的时间是某个团队对已完成工作的局部观察，仅用于演示方法，不是行业基准；所有输出均来自本地执行。

用观察利息排列候选项

脚本先把正在发生的事故排在首位，再比较根据已完成变更计算的季度观察利息。token-validation 的时间成本不是最高，但事故使它成为第一项。这个排序规则是团队的显式政策，不是技术债务的通用公式。

checkout-coupling 每季度观察到 12 小时利息，本金估算为 18 小时。这不证明两个季度后一定回本，因为未来变化次数和修复效果仍有不确定性。它只说明这项债务值得进一步拆分和验证，而 report-export 在当前证据下可以延后。

真实清单还应保留每个数字的时间窗口和证据链接。若「额外分钟」只是对理想代码库的猜测，就要标成估算，并与构建日志、变更复盘或历史中位数分开。伪精确会让讨论聚焦小数，而不是假设。

用特征测试保护现有行为

下一步不是立即替换旧实现，而是先记录调用者已经依赖的边界行为。 特征测试（characterization test） 描述代码当前可观察到的行为；它不保证该行为在业务上正确，因此每个用例仍需产品或领域负责人确认。

import assert from 'node:assert/strict';
function legacyShippingCents(subtotalCents, country) {
  if (country === 'FR') {
    return subtotalCents >= 5000 ? 0 : 700;
  }
  if (country === 'DE') {
    return subtotalCents >= 7000 ? 0 : 900;
  }
  return 1500;
}
const observedCases = [
  { subtotal: 4999, country: 'FR', expected: 700 },
  { subtotal: 5000, country: 'FR', expected: 0 },
  { subtotal: 6999, country: 'DE', expected: 900 },
  { subtotal: 7000, country: 'DE', expected: 0 },
  { subtotal: 8000, country: 'ES', expected: 1500 },
];
for (const testCase of observedCases) {
  const actual = legacyShippingCents(testCase.subtotal, testCase.country);
  assert.equal(actual, testCase.expected);
}
const policies = new Map([
  ['FR', { freeFrom: 5000, standard: 700 }],
  ['DE', { freeFrom: 7000, standard: 900 }],
]);
function shippingCents(subtotalCents, country) {
  const policy = policies.get(country);
  if (!policy) return 1500;
  return subtotalCents >= policy.freeFrom ? 0 : policy.standard;
}
for (const testCase of observedCases) {
  const actual = shippingCents(testCase.subtotal, testCase.country);
  assert.equal(actual, testCase.expected);
}
console.log(`characterized cases: ${observedCases.length}`);
console.log('refactor preserves observed behavior: true');

characterized cases: 5
refactor preserves observed behavior: true

第一个循环确认测试确实描述旧实现，第二个循环把同一组案例应用到数据驱动的新实现。两个循环都通过，只能证明列出的五个案例保持不变。货币范围、未知国家和输入类型仍需要契约测试或验证规则覆盖。

这次重构把国家政策从条件分支移到数据映射，使新增国家不必继续扩展嵌套分支。它没有改动外部函数的参数和返回单位，因此迁移范围较小。如果业务同时要求修改免邮门槛，应把行为变更与结构重构分别提交和验证，失败时才知道是哪类变化造成的。

用退出证据关闭债务

最后一个脚本把「代码已合并」与「债务可关闭」分开。记录只有在契约测试和依赖规则都存在时才进入 retired 状态。

const debt = {
  id: 'checkout-coupling',
  state: 'accepted',
  target: 'Checkout depends on a pricing port',
  evidence: [],
};

function requestRetirement(item) {
  const required = ['contract-tests', 'dependency-rule'];
  const missing = required.filter((name) => !item.evidence.includes(name));

  if (missing.length > 0) {
    return { ok: false, reason: `missing evidence: ${missing.join(', ')}` };
  }

  item.state = 'retired';
  return { ok: true, reason: 'target state verified' };
}

let result = requestRetirement(debt);
console.log(`${debt.state}: ${result.reason}`);

debt.evidence.push('contract-tests');
result = requestRetirement(debt);
console.log(`${debt.state}: ${result.reason}`);

debt.evidence.push('dependency-rule');
result = requestRetirement(debt);
console.log(`${debt.state}: ${result.reason}`);

accepted: missing evidence: contract-tests, dependency-rule
accepted: missing evidence: dependency-rule
retired: target state verified

契约测试证明端口两侧仍同意可观察行为，依赖规则则证明源码依赖方向已经改变。两类证据分别覆盖行为和结构，缺一项时记录保持 accepted。真实系统还可能要求遥测窗口、迁移数据核对和旧路径删除证明。

代码把证据写成名称数组只是为了保持示例短小。生产流程应保存可追溯引用，例如持续集成任务、测试报告或架构规则的位置，并检查引用对应当前版本。否则团队可能用一次过期的成功结果关闭后来再次出现的债务。

陷阱

**修复：**要求记录具体的未来变化、额外成本和目标状态。当前行为错误的项目进入缺陷流程，缺少的业务能力进入产品待办，只有会增加未来变更成本的选择进入债务清单。

**修复：**把工具结果当作候选信号，并连接到变化频率、事故、构建等待或真实返工。保留原始维度，不要用无法解释权重的单一健康分数替代判断。

**修复：**先用特征测试与遥测建立行为基线，再从频繁变化的边界切出小块。整体替换只有在增量接缝不可行、目标边界明确且迁移与回退都可验证时才成立。

**修复：**根据风险和即将发生的变化安排工作，并在计划中展示证据与机会成本。团队可以保留维护容量作为策略，但它不是每个周期都必须消费完的目标。

**修复：**把重要取舍连接到 ADR 或债务记录，明确复查日期或事件，并在目标状态满足时删除临时分支、开关和兼容层。关闭工单前检查遗留路径是否真的不可达。

AI 时代

由智能体协助偿还技术债务时，最终应消除已识别的维护负担，并退役临时兼容路径。例如，在替换遗留序列化器之前，智能体可以分析使其代价升高的变更和事故，用特征测试记录当前的空值、舍入、错误和副作用行为，再抽取一条经常变化的边界。随后让新旧路径对同一语料运行，在既定退出条件满足后删除开关，并测量当初证明这项工作有价值的构建或变更成本。这样得到的是关闭债务项的证据，而不是遗留第二套实现。

延伸阅读

• IEEE Software：Technical Debt From Metaphor to Theory and Practice
• IEEE TechDebt：Technical Debt Triage in Backlog Management
• IEEE SEAA：Architecture Technical Debt Understanding Causes and a Qualitative Model
• IEEE ICSE-SEIP：On the Lack of Consensus Among Technical Debt Detection Tools