Skip to content
返回维护与 LTS

技术债识别

在代码库中的捷径、变通和衰退变成紧急之前暴露它们。

为什么

技术债在变成不是之前是不可见的 — sprint 3 的捷径变成 sprint 20 的 2 天调试。识别使不可见变可见：你编目 TODO、重复逻辑、未测路径、落后两大版本的框架，突然你有可管理的清单而非模糊恐惧。目标不是零债（那不可能也不可取 — 债是换速度的工具）而是已知债有已知成本。不识别债的团队总被估算爆炸惊吓，因为债是"简单"功能花一周的原因，而没人把两者联系起来。

何时使用

持续 — 创建时在代码中标记（TODO(debt):），每季度盘点以暴露累积。

如何做

1. 创建时标记：每个捷径加 TODO(debt): <原因> 注释带工单链接
2. 跑静态分析：eslint（复杂度、重复）、knip（死代码）、dependency-cruiser（架构）
3. 搜债标记：grep -rn "TODO(debt)|FIXME|HACK|XXX" src/
4. 编目到 DEBT.md 或工单系统：每项有类型、位置、估算成本、利率（复合多快）
5. 分类：代码债（重复、复杂）| 设计债（耦合、缺抽象）| 测试债（未测路径）| 依赖债（过时）
6. 度量：跟踪圈复杂度、重复 %、测试覆盖、过时依赖数为趋势线
7. 每季度审清单；2 季度未动的项是显式接受的候选

示例

# 创建时标记债
// TODO(debt): 重复校验逻辑 — 提取到共享 schema
// 工单：https://tracker/issues/DEBT-42
function validateOrder(o) { /* 从 validateUser 复制 */ }

# 季度盘点脚本
grep -rn "TODO(debt)|FIXME|HACK" src/ > debt-raw.txt
npx eslint --rule '{"complexity":["error",15],"no-dupe-keys":"error"}' src/
npx knip --include dependencies,files,exports
npx dependency-cruiser --validate .dependency-cruiser.js src/

# DEBT.md 编目
| ID  | 类型   | 位置            | 成本  | 利率     | 年龄 |
|-----|--------|-----------------|-------|----------|------|
| D1  | code   | order.ts:重复   | 2h    | 高       | 3月  |
| D2  | test   | payment.ts:0覆盖| 4h    | critical | 6月  |
| D3  | dep    | react@16        | 2天   | 高       | 9月  |

常见问题

  • ⚠未标记债 — 无 TODO 的捷径无人知是捷径，被当设计永不偿还。
  • ⚠只量代码债（复杂度）而忽测试债 — 未测支付代码比复杂工具风险更高。
  • ⚠债清单存在但从不审 — 长到 500 项变成愧疚清单而非行动清单。

最佳实践

  • ✓每个捷径创建时标 TODO(debt): + 工单 — 无标签的债是你会忘的债。
  • ✓把债当趋势线（复杂度、重复 %、过时依赖）而非静态清单 — 平或降的线是目标。
  • ✓每季度审债清单并显式接受超 2 季度的项 — 接受是有效结果，否认不是。