用 Claude Code 安全降低技术债：团队实践指南

很多团队都说要还技术债，但每个迭代又被新功能挤满。几个月后，any 越来越多，依赖包落后两个大版本，CI 偶尔失败，TODO 也变成了永久注释。

Claude Code 不是让自动重构变成零风险的工具。它真正适合做的是：盘点债务、补上证据、排出优先级，并把偿还动作拆成可审查的小 PR。这样技术债不再是一次危险的大扫除，而是团队可以持续执行的流程。

本文给出一套面向团队的实战流程，覆盖 code smell（会让未来修改变难的代码异味）、依赖债、flaky test（时好时坏的不稳定测试）、重复逻辑、危险 TODO、ICE/RICE 评分、小 PR 策略和治理规则。官方资料可参考 Claude Code Common workflows、Memory 和 Settings。站内也建议配合阅读 测试策略指南、CLAUDE.md 最佳实践 和 审批与沙箱指南。

把技术债变成偿还循环

失败的做法通常是“找一周集中重构”。分支变得很大，评审者看不出行为有没有改变，最后在发布前被回滚。

更稳的方式是短循环。

flowchart LR
  A["盘点"] --> B["收集证据"]
  B --> C["用 ICE/RICE 评分"]
  C --> D["拆成小 PR"]
  D --> E["测试和评审"]
  E --> F["更新债务台账"]
  F --> A

盘点不是凭感觉说“这里很脏”。要收集文件路径、行号、CI 日志、过期依赖、any、大文件、重复逻辑、TODO/FIXME 等可讨论的证据。

做法	适合场景	风险	Claude Code 的用法
大型重构项目	框架迁移、边界清楚的改造	diff 太大，评审困难	只做调研和迁移计划
小型偿还 PR	日常维护	影响看起来不明显	台账、评分、PR 检查表
依赖升级冲刺	安全修复、EOL 包	破坏性变更藏在细节里	changelog 摘要和测试计划
flaky test 清理	CI 已经不被信任	重跑掩盖真实 bug	失败分类和复现步骤

用例1：盘点 code smell

code smell 不一定是 bug。它更像一个信号：未来改动会变难。例如巨大的函数、职责过多的类、重复校验、没有解释的 magic number、绕过类型系统的写法。

先让 Claude Code 只检查，不改文件。

claude -p "
检查 src/ 和 tests/ 中的技术债。现在不要修改任何文件。

关注:
- 超过 80 行的函数
- 超过 300 行的文件
- 超过 4 层的嵌套
- 重复的输入校验、日期处理、权限检查
- TypeScript any、as any、@ts-ignore
- TODO / FIXME / HACK 注释
- 没有测试覆盖的分支，或只检查渲染的空测试

输出为可粘贴到 docs/tech-debt/register.md 的 Markdown 表格。
列为 ID, File, Line, Debt type, Evidence, Risk, Suggested first PR, Confidence。
"

“不要修改文件”很重要。否则 Claude Code 可能在证据还不充分时就开始整理代码。先让它调查、分类、提出假设，再由团队决定第一笔要还的债。

用例2：发现依赖债

过期库、无人维护的包、安全漏洞、同一用途的重复库，都是技术债。只看 npm audit 数量很容易误判：噪音警告会抢走注意力，而真正接近 EOL 的核心依赖可能被忽略。

claude -p "
基于 package.json、lockfile、npm outdated 和 npm audit 输出，分类依赖债。

分类:
1. 必须修复的安全问题
2. 需要 major update 且可能有破坏性变更
3. 无人维护或官方建议替换
4. 同一用途的重复库
5. 可以暂缓

对每一项写出影响范围、优先阅读的 changelog、需要跑的测试、最小安全 PR。
把可以自动更新的项和必须人工评审的项分开。
"

依赖更新不能因为测试跑过一次就算安全。日期处理、认证、加密、路由、构建工具和测试运行器都应该单独分支，并写清回滚方式。

用例3：偿还 flaky test 和重复逻辑

flaky test 会破坏 CI 的信誉。一旦大家相信“重跑就会过”，测试套件就不再是安全网。

claude -p "
阅读最近 20 次 CI 失败日志，分类可能的 flaky test。

分类维度:
- 依赖时间、时区或随机数据
- 依赖网络或外部 API
- 测试之间共享状态泄漏
- 异步等待方式不稳定
- 更像产品 bug，不能标记为 flaky

对每个候选项给出复现命令、最小修复方案和需要新增的断言。
"

重复逻辑也要小步处理。如果权限检查在四个文件里复制，第一 PR 只抽出纯函数并用测试锁住行为。后续 PR 再逐个替换调用点，评审者才能判断行为是否一致。

可复制的简易扫描脚本

Claude Code 擅长分析，但机械标记也应该脚本化。把下面内容保存为 scripts/debt-scan.mjs，然后运行 node scripts/debt-scan.mjs src。

import fs from "node:fs";
import path from "node:path";

const root = process.argv[2] || "src";
const maxLines = Number(process.env.MAX_LINES || 300);
const extensions = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
const findings = [];

function walk(dir) {
  if (!fs.existsSync(dir)) return;

  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);

    if (entry.isDirectory()) {
      if ([".git", "node_modules", "dist", "build", ".next", "coverage"].includes(entry.name)) continue;
      walk(fullPath);
      continue;
    }

    if (entry.isFile() && extensions.has(path.extname(entry.name))) {
      scanFile(fullPath);
    }
  }
}

function add(file, line, type, severity, detail) {
  findings.push({ file, line, type, severity, detail });
}

function scanFile(file) {
  const text = fs.readFileSync(file, "utf8");
  const lines = text.split(/\r?\n/);

  if (lines.length > maxLines) {
    add(file, 1, "large-file", 3, `${lines.length} lines`);
  }

  lines.forEach((line, index) => {
    const lineNumber = index + 1;

    if (/\b(FIXME|TODO|HACK)\b/i.test(line)) {
      add(file, lineNumber, "unsafe-comment", /FIXME|HACK/i.test(line) ? 4 : 3, line.trim());
    }

    if (/\.(ts|tsx)$/.test(file) && /(:\s*any\b|as\s+any\b|<any>)/.test(line)) {
      add(file, lineNumber, "typescript-any", 4, line.trim());
    }
  });
}

walk(root);

console.log("| file | line | type | severity | detail |");
console.log("| --- | ---: | --- | ---: | --- |");
for (const item of findings.sort((a, b) => b.severity - a.severity || a.file.localeCompare(b.file))) {
  const detail = item.detail.replaceAll("|", "\\|");
  console.log(`| ${item.file} | ${item.line} | ${item.type} | ${item.severity} | ${detail} |`);
}

if (findings.length === 0) {
  console.error("No obvious debt markers found.");
}

这个脚本不理解架构，也不能找出所有重复逻辑。但它能每周用同一把尺子收集 TODO、FIXME、any 和大文件，给讨论一个稳定起点。

债务台账模板

先把候选项放进一个台账，再拆 issue 或 PR，会更容易比较优先级。

# Technical Debt Register

| ID | Area | Evidence | User or team impact | ICE | RICE | Owner | Next PR | Status |
| --- | --- | --- | --- | ---: | ---: | --- | --- | --- |
| TD-001 | Auth permissions | src/auth/guard.ts duplicates role checks in 4 places | New role changes take 2 days and often miss one path | 420 | 1680 | Backend | Extract pure canAccess() with tests | Ready |
| TD-002 | Dependencies | vite is 2 major versions behind | Security patches and plugin updates are blocked | 280 | 900 | Platform | Upgrade in isolated branch and run build/test | Investigating |

## Scoring note

- ICE = Impact x Confidence x Ease
- RICE = Reach x Impact x Confidence / Effort
- Keep evidence links concrete: file path, line, CI run, or user-facing incident.

ICE 适合快速排序。RICE 适合需要把影响人数和工作量讲清楚的时候。它们不是绝对真理，而是让讨论一致的工具。

安全重构计划提示词

确定要偿还的项目后，先让 Claude Code 写计划，不要直接改。

claude -p "
为 TD-001 制定安全偿还计划。现在不要修改文件。

范围:
- src/auth/guard.ts
- src/auth/roles.ts
- tests/auth/guard.test.ts

约束:
- 不改变外部 API 行为
- 先检查现有测试
- 如果行为缺少测试，先添加 characterization tests 再重构
- PR 目标控制在 300 行变更以内
- 写出风险、回滚方案和评审重点

输出:
1. 当前行为总结
2. 明确不做的事
3. 第一个 PR 的差分计划
4. 要执行的测试命令
5. PR 评审请求文案
"

“明确不做的事”可以防止过度帮忙。边界写清楚后，Claude Code 产出的差分更容易评审。

重构 PR 检查表

## Refactor PR checklist

- [ ] This PR changes structure, not product behavior.
- [ ] Existing behavior is covered by tests before the refactor.
- [ ] New helper names describe domain behavior, not implementation detail.
- [ ] Public API, response shape, permissions, and logging are unchanged or explicitly documented.
- [ ] The diff is small enough to review in one sitting.
- [ ] Rollback is simple: revert this PR without reverting unrelated work.
- [ ] The debt register is updated with status and follow-up PRs.

把这段放进 Claude Code 生成的 PR 正文，可以把“相信我只是重构”变成可检查的证据。

具体坑点

过度相信自动修改 类型通过不代表安全。认证授权、计费、日期、异步处理、数据库迁移都需要行为固定测试和人工评审。

把所有 TODO 都删掉 有些 TODO 是发布阻断，有些只是未来备忘。优先处理 remove before release、bypass auth、temporary token、FIXME 这类危险词。

把依赖升级打包太大 十个 major update 放进一个 PR，会让失败排查变得很慢。构建工具、UI 库、认证库、测试运行器要拆开。

把评分当成政治工具 ICE/RICE 必须带证据，而不是谁声音大谁分高。记录文件路径、CI 运行、事故和工时假设。

没有留下团队记忆 “权限代码必须审批”“重构 PR 控制在 300 行以内”等规则，应写进 CLAUDE.md 或项目设置。Claude Code 的 Memory 和 Settings 可以减少重复说明。

团队治理方式

建议每周 30 分钟做一次技术债评审：

1. 查看扫描脚本和 Claude Code 的盘点结果。
2. 只更新前 10 项的 ICE/RICE。
3. 为下个迭代选择 1 个偿还 PR。
4. 对 flaky test 和安全依赖提高优先级。
5. PR 完成后，在台账记录“哪里变轻松了”。

ClaudeCodeLab 可以帮助团队把这套流程落地为台账模板、PR 检查表、Settings 和 CLAUDE.md 初始规则。如果希望按你的仓库和评审文化定制，请查看 Claude Code 培训、模板和咨询。

总结

用 Claude Code 降低技术债的安全做法，不是让它“一次性重构全部代码”。正确顺序是收集证据、评分排序、一次偿还一个小 PR。code smell、依赖债、flaky test、重复逻辑和危险 TODO 都能放进同一条循环。

实际试用本文流程后，Masa 的小型项目里最有价值的变化是“紧急要还的债”和“先记录即可的债”被分开了。把 any 清理和旧 TODO 删除拆成小 PR 后，评审负担没有明显增加，但不安定区域减少了。相反，依赖 major update 比预想更重，因此更安全的顺序是先补测试和发布说明，再让 Claude Code 起草实际改动。