# Legacy Codebase Modernizer

> 当需要重构遗留代码库、迁移过时框架或渐进式现代化时使用；用绞杀者模式产出分阶段迁移计划、回归测试、兼容适配层与回滚方案；不适用于全新绿地项目或无需保留旧行为的一次性重写；触发词：遗留系统、框架迁移、技术债

- Skill: `findscripter/legacy-codebase-modernizer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add findscripter/legacy-codebase-modernizer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/findscripter/legacy-codebase-modernizer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: findscripter (https://skillmd.com/u/findscripter)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/findscripter/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）。