如何用 Claude Code 可视化并系统性地减少技术债务

“我们想重构但总是没时间。""到底从哪里开始？“技术债务在悄无声息中不断累积。借助 Claude Code，你可以系统性地揭露、排序并偿还债务，成本仅为常规的一小部分。

1. 在整个代码库中检测 Code Smells

从一次完整的扫描开始。

claude -p "
扫描 src/ 查找 code smells，检查：

- 超过 50 行的函数
- 深层嵌套（4 层以上）
- 重复的逻辑
- God Classes（职责过重）
- 魔法数字
- 未使用的 exports
- any 类型的使用
- TODO / FIXME 注释

以如下格式输出到 docs/tech-debt/smells.md：
| File | Line | Smell | Severity(1-5) | Suggested fix |
"

一份按严重度排序的清单将成为你的起点。

2. 衡量依赖债务

过时的库和漏洞同样是债务。

claude -p "
分析 package.json，结合 npm audit 和 npm outdated：

1. 需要 major 更新的库
2. 已知漏洞
3. 停止维护的包
4. 重复引入（例如 moment 和 date-fns 混用）

以表格形式输出到 docs/tech-debt/dependencies.md，包含当前版本、最新版本、breaking changes、更新优先级。
"

3. 使用 ICE Score 排序优先级

你无法修复所有问题。按 Impact × Confidence × Ease 进行排序。

claude -p "
基于 docs/tech-debt/smells.md 和 dependencies.md，为每一项打分：

- Impact (I)：对业务/开发速度的影响（1-10）
- Confidence (C)：影响的确定性（1-10）
- Ease (E)：修复难度（1-10）

按 Score = I × C × E 降序排列。
输出为 docs/tech-debt/backlog.md。
为前 10 项包含预估人日。
"

数值化评分能向产品经理清晰阐明理由。

4. 自动生成小型偿还 PR

将偿还拆分为可审查的 PR。

claude -p "
针对 docs/tech-debt/backlog.md 中的第 1 项：

1. 创建分支：refactor/tech-debt-001
2. 仅修复该问题（不改变行为）
3. 验证现有测试通过
4. 如果太大则拆分为多个 commit
5. 执行 gh pr create

PR 正文应包含：
- 这笔债务是什么
- 为什么现在偿还
- ICE 评分
- 对其他代码的影响范围
"

5. 识别未被测试的热点

低覆盖率的区域会成为未来的债务。

npm test -- --coverage --coverageReporters=json

claude -p "
分析 coverage/coverage-summary.json：

- 覆盖率低于 50% 的文件
- 其中包含业务逻辑的文件
- 添加测试的优先级

输出到 docs/tech-debt/coverage-gaps.md。
为前 3 个文件提出测试用例建议。
"

与测试自动生成结合，效果相乘。

6. 用周报让偿还可见

没有可见性，团队会放弃。

claude -p "
报告过去一周的技术债务偿还情况：

- 已解决的项（查看 docs/tech-debt/backlog.md）
- 新发现的债务
- 仍未解决的 5 级严重项
- 依赖更新进度

输出到 docs/tech-debt/weekly-report-$(date +%Y-%m-%d).md。
调整为适合 5 分钟站会朗读的篇幅。
"

用 cron 安排在周一早晨运行，将偿还制度化。

7. 在入口堵住新债务

如果流入持续，偿还就是徒劳。在 CLAUDE.md 中编码规则。

## 防止新技术债务的规则

### 禁止
- 新的 any 类型值（不可避免时使用带原因的 // @ts-expect-error）
- 没有 TODO 的权宜之计
- 没有测试的业务逻辑

### PR 检查清单
- [ ] 新代码覆盖率 ≥ 80%
- [ ] 零 ESLint 错误
- [ ] 新增依赖在 PR 中有充分理由

### 可接受的例外
- 热修复（附带后续 ticket）
- POC 代码（上生产前必须重写）

通过 pre-commit hook 强制执行。参见 Hooks 指南。

反模式

❌ 一个巨大的重构 PR

“一次修复所有”的 PR 无法审查。一个 smell = 一个 PR。

❌ 混合行为变更

绝不将功能工作与重构混在同一个 PR。审查负担会翻倍。

❌ 没有测试的重构

覆盖率低时，先写测试，再重构。没有安全网就意味着新 bug。

结论

• 用 Claude Code 揭露 smells、依赖债务和覆盖率缺口
• 用 ICE scoring 量化优先级
• 将偿还拆分为小型 PR
• 发布每周进度报告
• 通过 CLAUDE.md 规则封堵新债务
• 一个 smell = 一个 PR

技术债务不是”某一天”才要修复的东西，而是每周偿还一点。Claude Code 大幅降低了这种节奏的成本。

相关：重构自动化 / 遗留代码现代化 / 代码评审清单

官方文档：Anthropic Claude Code