Legacy Codebase Modernizer

---
name: legacy-codebase-modernizer
title: 遗留系统现代化重构
description: 当需要重构遗留代码库、迁移过时框架或渐进式现代化时使用；用绞杀者模式产出分阶段迁移计划、回归测试、兼容适配层与回滚方案；不适用于全新绿地项目或无需保留旧行为的一次性重写；触发词：遗留系统、框架迁移、技术债
domain: 研发/architecture
triggers: [遗留系统, 遗留代码, 现代化重构, 框架迁移, 技术债, 依赖升级, 向后兼容, 绞杀者模式, 单体拆分, 微服务拆分, Java 8 升级, Python 2 到 3, jQuery 迁移 React, 旧系统改造]
tags: [研发, misc, 重构, 迁移, 技术债, 兼容性, 测试]
level: 进阶
status: stable
agents: [claude-code, codex, cursor, gemini-cli]
tools: [Read, Edit, Grep, Glob, Bash]
requires: []
related: [clean-code-principles, code-simplifier, database-migration-strategies, zero-downtime-migration-architect]
combines_with: [test-coverage-gap-finder, clean-code-principles, adr-management-patterns]
license: MIT
source: sickn33/agentic-awesome-skills
source_license: MIT
---
## 何时使用

适用场景：

- 框架/语言版本迁移：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）。