技术债跟踪与度量

用趋势线客观度量债，使偿还可见且策略数据驱动。

为什么

主观债评估（"代码库感觉乱"）不可行动且丧气 — 你不能趋势化感觉。客观指标 — 圈复杂度、重复 %、测试覆盖、过时依赖数、TODO 数 — 把债变成可画、可趋势、可设目标的数。度量也改行为：复杂度在仪表盘上时工程师重构以移数。无指标则还债对领导不可见故被砍；有指标则降势是可见胜利维持投资。目标不是单数而是一小组正交指标共描代码库健康。

何时使用

CI 中设一次指标，然后每 sprint 趋势。任一指标退化超阈值则告警。

如何做

1. 选 4-6 正交指标：复杂度、重复 %、覆盖、过时依赖数、TODO(debt) 数、构建时间
2. 埋点：eslint（复杂度/重复）、c8/istanbul（覆盖）、npm outdated（依赖）、grep（TODO）
3. 发到仪表盘：Code Climate、SonarQube 或简单 JSON + Grafana
4. 设阈值：复杂度 >15/函数、覆盖 <70%、过时依赖 >10 则 CI 失败
5. 每 sprint 趋势：存快照、画线、sprint review 审
6. 回归告警：PR 升复杂度 >5 或降覆盖 >2% 则阻塞
7. 仪表盘对全队公开 — 可见是重点

示例

# CI 债指标作业（GitHub Actions）
- name: 复杂度与重复
  run: npx eslint --rule '{"complexity":["warn",15]}' --format json src/ > complexity.json
- name: 覆盖
  run: npx c8 --reporter=json npm test
- name: 过时依赖
  run: npm outdated --json > outdated.json
- name: TODO 数
  run: grep -rc "TODO(debt)" src/ | wc -l > todo-count.txt

# 阈值门控（PR 失败）
node scripts/check-debt-thresholds.js
# 若 复杂度 > 15 均值 || 覆盖 < 70 || 过时 > 10 -> exit 1

# 趋势快照（每 sprint 存）
# debt-snapshots/sprint-42.json
{ "complexity": 8.2, "duplication": 3.1, "coverage": 78,
  "outdated": 6, "todos": 14, "buildMs": 42000 }
# Grafana 画线；sprint review 审趋势线。

常见问题

⚠只跟一指标（覆盖）且刷它 — 100% 覆盖但无断言测试比 60% 真断言更糟。
⚠指标在 CI 但不在仪表盘 — 工程师看不到趋势，数不驱动行为。
⚠无回归门控 — 升复杂度 10 的 PR 因 CI 只查"能构建"不查"腐烂"而发。

最佳实践

✓跟 4-6 正交指标而非一 — 单指标可刷；面板诚实。
✓CI 中放回归门控阻塞退化超阈值的 PR — 防腐烂而非只量。
✓趋势仪表盘对全队公开且每 sprint review 审 — 可见驱动偿还。