SOP：重构迁移
用 Vibe Coding 安全重构代码、升级依赖、迁移架构的标准流程。
适用场景
- 重构旧代码（消除重复、改善结构、提升可读性）
- 升级依赖版本（框架升级、包版本更新）
- 架构迁移（从单体到微服务、从 REST 到 GraphQL、从 MySQL 到 PostgreSQL）
前置条件
- 项目已有完整的测试套件（没有测试就不能安全重构）
- 有 git 仓库，每个步骤都能回退
- 重构范围已经评估清楚
流程步骤
步骤 1：评估影响
重构前必须评估风险和影响范围。
直接复制风险评估表填写：
| 维度 | 评估内容 | 你的评估 |
|---|---|---|
| 变更范围 | 涉及多少文件？多少行代码？ | [填写] |
| 依赖关系 | 变更的模块被多少其他模块依赖？ | [填写] |
| 测试覆盖 | 变更区域有没有测试？覆盖率多少？ | [填写] |
| 回退难度 | 如果重构失败，能回退吗？回退成本多高？ | [填写] |
| 业务影响 | 变更是否影响线上用户？有 downtime 吗？ | [填写] |
风险等级判定：
| 总体风险 | 特征 | 推荐策略 |
|---|---|---|
| 低 | 少文件、少依赖、有测试、易回退 | 一次完成，1-2 个会话 |
| 中 | 多文件、有测试、回退可行 | 分批执行，每批 2-3 个文件 |
| 高 | 大范围、测试不全、回退困难 | 分批执行 + 每批独立验证 + 人工审查每个变更 |
让 Claude 做初步评估：
用 Plan Mode 评估重构 [目标模块] 的影响：
1. 列出所有需要变更的文件
2. 分析每个文件的依赖关系（谁依赖它、它依赖谁）
3. 检查相关测试的覆盖情况
4. 评估风险等级
在 plan.md 中写出评估结果和重构方案。不要修改任何代码。步骤 2：制定重构计划
让 Claude 在 Plan Mode 中生成详细重构方案：
读取 plan.md 的评估结果。生成重构实施计划：
1. 按什么顺序变更？（从最独立的模块开始，到最核心的模块）
2. 每批变更包含哪些文件？
3. 每批变更后如何验证？（跑什么测试）
4. 如果某批变更失败，回退策略是什么？
约束：
- 每批变更不超过 3 个文件
- 每批变更后必须能通过现有测试
- 保持对外接口不变（内部重构，外部不动）审查重点：
- 变更顺序是否正确？（先改底层 → 再改上层？还是反过来？）
- 是否有遗漏的文件？
- 对外接口是否真的不变？
步骤 3：分批执行
每批在一个会话中完成：
执行重构计划中的第 [N] 批：变更 [文件列表]。
完成后运行测试确认所有测试通过。如果有测试失败，最多尝试修复两次。每批执行后的 checklist：
| 检查项 | 状态 |
|---|---|
| 变更文件是否与计划一致 | [ ] |
| 测试是否全部通过 | [ ] |
| 对外接口是否不变 | [ ] |
| 没有引入新的 lint 错误 | [ ] |
通过后：git add + git commit（checkpoint commit）。
步骤 4：逐批验证
每批独立验证比全部完成后一次验证更安全。 因为：
- 如果第 3 批有问题，你只需要回退第 3 批，不用从头重来
- 每批验证缩小了"问题出在哪里"的搜索范围
- 逐步确认对外接口不变
步骤 5：收尾清理
所有批次完成后：
检查重构后的整体状态：
1. 运行完整测试套件和 lint
2. 搜索是否有残留的旧代码引用（如 import 旧模块路径、调用旧函数名）
3. 确认没有遗留的 TODO 或临时注释
4. 更新 CLAUDE.md 中与重构相关的描述（如模块路径变了）特殊场景
依赖升级 checklist
markdown
## 依赖升级：[包名] 从 [旧版本] 到 [新版本]
### 升级前
- [ ] 阅读 changelog / migration guide
- [ ] 确认 breaking changes 列表
- [ ] 在测试分支上升级
- [ ] 运行现有测试确认 baseline
### 升级中
- [ ] 执行升级命令
- [ ] 修复 breaking changes 导致的错误
- [ ] 运行测试
- [ ] 检查是否有新的 API 可用（优化机会）
### 升级后
- [ ] 全量测试通过
- [ ] 手动验证核心功能
- [ ] 更新 CLAUDE.md 中的版本信息
- [ ] 合并到主分支架构迁移决策树
是否需要迁移架构？
├─ 否 → 保持现有架构，只做局部重构
├─ 是 → 迁移范围有多大？
├─ 小（1-2 个模块）→ 在一个 feature 分支完成
├─ 中（核心模块）→ 分批在 feature 分支完成 + 每批验证
└─ 大（整个系统）→ 新仓库/新分支 + 逐步迁移 + 双系统并行过渡常见问题
Q：没有测试怎么重构？ A：先让 Claude 写测试。"为 [要重构的模块] 写测试，覆盖当前所有行为。测试通过后再开始重构。" 没有测试的重构是赌博。
Q：重构中发现需要改对外接口怎么办？ A：停下来。更新 spec/plan，重新评估影响。不要在执行中临时决定改接口——这会让下游模块出问题。
Q：依赖升级后大量测试失败怎么办？ A：不要让 AI 逐个修复——先让 Claude 分析所有失败的模式，判断是否是同一个 breaking change 导致。"分析所有测试失败，按原因分类。列出 breaking changes 的影响范围和批量修复策略。"