Legacy codebase modernizer

何时使用

适用场景：

• 框架/语言版本迁移：jQuery→React、Java 8→17、Python 2→3 等。
• 数据库现代化：存储过程→ORM。
• 单体拆分为微服务（按业务域逐步剥离）。
• 依赖升级与安全补丁修复。
• 为缺测试的遗留代码补回归测试。
• API 版本化与向后兼容治理。

不该用（负边界）：

• 全新绿地项目，没有遗留约束——直接按现代最佳实践开发即可。
• 业务明确可一次性废弃、无需保留旧行为的「推倒重写」。
• 任务与遗留改造无关，或属于其他领域/工具范畴。

核心原则：以风险控制为先。在没有迁移路径前，绝不破坏现有功能。

步骤

1. 澄清目标、约束与必需输入：现代化要达成什么、有哪些不可破坏的契约、缺失哪些权限或环境。若关键输入、安全边界或验收标准缺失，停下来追问，不要擅自假设。
2. 先加测试再重构（characterization test）：用回归测试锁定遗留代码当前的真实行为（含 bug 行为），作为重构的安全网。
3. 采用绞杀者模式（Strangler Fig）：新实现包裹在旧实现外围，按模块逐步替换、逐步引流，而非大爆炸式替换。
4. 维持向后兼容：通过兼容垫片（shim）/适配层让新旧接口共存，旧调用方无感。
5. 用特性开关（feature flag）灰度放量：按比例切流，出问题可秒级回退。
6. 清晰记录破坏性变更与弃用时间表，并为每个阶段准备回滚流程。
7. 验证：每阶段都做环境内的实际测试与回归校验，不把产出当作替代专家评审或真实环境验证的依据。

指令

• 澄清目标、约束与必需输入。
• 应用相关最佳实践并验证结果，给出可执行步骤与验证手段。
• 关键约束（务必遵守）：
  • 绞杀者模式——渐进替换，不做大爆炸迁移。
  • 重构前先补测试。
  • 全程维持向后兼容。
  • 清晰记录破坏性变更。
  • 用特性开关做灰度放量。

应交付的产物：

• 含阶段与里程碑的迁移计划。
• 保持原有功能的重构后代码。
• 覆盖遗留行为的测试套件。
• 兼容垫片/适配层。
• 弃用告警与时间表。
• 每个阶段对应的回滚流程。

示例

以「Python 2 → 3 迁移」为例：

1. 锁行为：对核心模块补 characterization test，运行 pytest 记录当前输出基线。
2. 兼容过渡：先引入 six（或 python-future）写出 2/3 双兼容代码，让两个解释器都能跑通测试。
3. 静态扫描与自动改写：用 python-modernize 或 2to3 -w -n <path> 生成 diff，逐文件 review 后再应用，避免盲目批量改写。
4. 逐模块切换：按依赖拓扑从叶子模块向上替换，每替换一块就跑全量回归。
5. 灰度上线：用特性开关把 Py3 路径按比例放量，监控告警，异常即回滚到 Py2 路径。
6. 收尾：移除 six 垫片与开关，发布弃用公告与下线时间表。

同理，「jQuery→React」可在页面级用适配层包裹旧 DOM 组件逐页替换；「存储过程→ORM」先用 ORM 包一层等价查询并比对结果再切换。

注意事项

• 永远先有迁移路径再动手，不要在没有回退方案时破坏既有功能。
• characterization test 锁的是「现状行为」，包括已有 bug；行为修正应作为独立、显式的变更，与迁移分开。
• 自动化改写工具（2to3、modernize、codemod）的输出必须人工 review，不可直接合入。
• 拆分单体时按业务域边界切，避免制造分布式单体。
• 破坏性变更要有明确弃用窗口与公告，给下游调用方留迁移时间。
• 产出不能替代环境相关的验证、测试与专家评审。

互见

• 测试补齐与回归保障类技能（characterization/回归测试）。
• 依赖与安全补丁升级类技能。
• 微服务拆分与 API 版本化类技能。

---

采编自 sickn33/antigravity-awesome-skills（MIT）。