接手一个没有测试、满是 callback hell、5 年前写的 Node.js 项目——这是每个开发者的噩梦。但有了 Claude Code，大规模重构不再是几个月的痛苦，而是有节奏、可验证的系统工程。
重构的根本原则：安全第一
在任何重构开始之前，牢记：
重构 = 功能不变，代码结构改变
每一步都要能验证功能没有被破坏。没有测试的代码库，重构第一步是写测试，不是改代码。
四步系统化重构流程
Step 1：侦察阶段——了解你在面对什么
对这个项目做全面的技术债务分析：
1. 代码质量：找出最复杂的 10 个函数（圈复杂度最高）
2. 依赖状况：有哪些过时的依赖？有安全漏洞吗？
3. 测试覆盖：当前测试覆盖率是多少？哪些模块完全没有测试？
4. 架构问题：有哪些明显的反模式？（全局状态、上帝对象、循环依赖）
5. 技术债务优先级：按影响程度和改造难度分级
输出一份技术债务报告，包括改造建议和预估工作量
结果示例：
技术债务报告：
🔴 高优先级：
- src/app.js（600行，圈复杂度 42）：业务逻辑和路由混在一起
- callback hell：auth/ 目录 3 层嵌套回调，无法维护
- 无测试覆盖：支付模块（payment/）零测试
🟡 中优先级：
- 依赖过时：lodash 3.x（当前 4.x，有安全补丁）
- 重复代码：数据验证逻辑在 5 个地方复制粘贴
🟢 低优先级：
- 命名不一致：部分变量用 snake_case，部分用 camelCase
Step 2：建立安全网——补测试
绝对不能跳过这一步。重构前必须有测试，才知道改动没有破坏功能。
为 src/auth/ 目录写集成测试：
- 覆盖正常登录流程
- 覆盖 token 过期场景
- 覆盖权限不足的情况
- 不要 mock 业务逻辑，只 mock 外部 I/O（数据库、Redis）
写完后运行，确认测试通过（当前代码应该通过）
有了测试，每次重构后运行测试，绿灯 = 安全，红灯 = 哪里出错了。
Step 3：分批改造——从最高优先级开始
不要试图一次性重构整个项目。按模块拆分，每个模块独立分支：
重构 src/auth/ 的 callback hell 为 async/await：
1. 先在 Plan Mode 分析需要改动哪些文件
2. 逐个函数改造，保持功能完全一致
3. 每改一个函数，运行 auth 相关测试确认通过
4. 完成整个 auth/ 改造后，运行完整测试套件
5. 提交为单独的 PR：refactor: convert auth module to async/await
关键：每个 PR 只做一件事，方便 review 和回退。
Step 4：持续验证
重构完成后，做一次全面验证：
1. 运行完整测试套件
2. 检查 bundle size 是否变化（前端项目）
3. 做性能对比（重构前后关键接口的响应时间）
4. 检查是否引入了新的 lint 警告
实际案例：callback hell → async/await
重构前（典型遗留代码）：
javascript
// 恶臭的三层回调嵌套
function authenticateUser(username, password, callback) {
db.findUser(username, function(err, user) {
if (err) return callback(err);
if (!user) return callback(new Error('User not found'));
bcrypt.compare(password, user.password, function(err, match) {
if (err) return callback(err);
if (!match) return callback(new Error('Invalid password'));
jwt.sign({ userId: user.id }, SECRET, function(err, token) {
if (err) return callback(err);
callback(null, token);
});
});
});
}Claude Code 的重构指令：
重构 src/auth/authenticate.js 的 authenticateUser 函数：
1. 将 callback 风格改为 async/await
2. 用 try/catch 替代 err-first callback 错误处理
3. 保持函数签名（对外接口）不变，用 util.promisify 包装已有测试
4. 改完后运行 npm test -- --testPathPattern=auth 确认通过
重构后：
javascript
// 清晰的 async/await 版本
async function authenticateUser(username, password) {
const user = await db.findUser(username);
if (!user) throw new Error('User not found');
const match = await bcrypt.compare(password, user.password);
if (!match) throw new Error('Invalid password');
return jwt.sign({ userId: user.id }, SECRET);
}用 /batch 大规模并行重构
对整个代码库做一类改动时，用 /batch 命令：
/batch 将 src/ 下所有使用 var 声明变量的文件改为 const/let，
遵循 ESLint 规则（赋值用 let，不赋值用 const），
改完每个文件后运行对应的测试，
每个文件提交一个独立的 commit
Claude Code 自动：
- 列出所有涉及文件
- 展示改动计划，等你确认
- 多代理并行处理每个文件
- 每个文件改完运行测试
- 自动提交
安全重构的核心策略
1. 永远先写测试
在重构 payment/ 模块之前，先为现有功能写回归测试。
目标：捕获当前行为（包括可能的 bug），
保证重构后行为完全一致。
2. 小步前进，频繁提交
把 UserService 的重构分成 5 个独立 PR：
PR1：提取数据库操作到 UserRepository
PR2：将回调改为 async/await
PR3：添加输入验证层
PR4：提取常量和配置
PR5：补充测试覆盖
3. 保留旧接口一段时间
重构 API 层时，保留旧的 /api/v1 端点，
新增 /api/v2，让客户端逐步迁移。
在旧端点加上 deprecation 日志，
3 个月后再删除旧端点。
4. 用 Git Bisect 定位问题
如果重构后出现 Bug：
帮我用 git bisect 找出是哪个 commit 引入了这个 Bug：
Bug 表现：[描述]
最后正常的版本：[commit hash 或日期]
遗留项目重构优先级框架
| 优先级 | 情况 | 策略 |
|---|---|---|
| 🔴 立刻处理 | 有安全漏洞 | 单独 hotfix PR，不要混入重构 |
| 🔴 高优先 | 阻碍日常开发的技术债务 | 下个 Sprint 安排 |
| 🟡 中优先 | 性能问题、可读性差 | 功能开发时顺手改 |
| 🟢 低优先 | 代码风格、命名 | 有时间再做，或用 /batch 批量处理 |
来源：Anthropic 官方最佳实践 + 工程师实战经验