用途：为复杂代码迁移与重构提供系统化流程，强调安全护栏与回滚能力，适用于依赖大版本升级、框架迁移（如 React class→hooks、Flask→FastAPI、Django→DRF）、语言现代化（Python 2→3、JavaScript→TypeScript）、跨文件大规模重构、带数据转换的数据库模式演进，以及从单体中提取服务的 monorepo 拆分。
核心工作流分四阶段：分析阶段确定影响范围、建立跨文件依赖图、查找破坏性变更并评估风险；规划阶段制定有序迁移计划、定义可编译可运行的中间检查点、设计回滚策略并估算成本；执行阶段分阶段增量修改，在每个检查点验证编译与测试、更新文档与 ADR，并按检查点逐个提交；验证阶段运行完整测试套件、做性能测试、代码评审并带监控上线。
迁移模式包括：渐进迁移（旧 API→兼容层→新 API→移除旧 API）、功能开关、绞杀者模式（单体→代理→新服务）和并行实现（旧系统只读+数据同步→新系统写入）。破坏性变更分析需检查 CHANGELOG、弃用警告、被移除或改名的 API、默认行为变化、环境与依赖变化，并查阅迁移指南和社区已知问题。跨文件依赖追踪涵盖导入、继承、接口实现和函数调用；Python 可用 pydeps、importlab，JavaScript/TypeScript 可用 dependency-cruiser、madge，Java 可用 jdeps、classycle，Go 可用 godepgraph，Rust 可用 cargo-deps。
安全模式包括快照测试、基于属性的测试和灰度发布（先 1% 流量，监控错误率与延迟，再逐步放大，异常则回滚）。回滚策略包括 git revert、功能开关关闭（如 USE_NEW_PARSER = False）和数据库迁移回滚脚本。Python 2→3 示例命令为 2to3 -w --output-dir=src_py3 src/。
限制与注意：应避免一次性大 PR、无文档化回滚策略、单个提交内迁移多个主依赖、跳过检查点验证；自动化测试不能替代人工评审。更多细节见 references/migration-patterns.md、references/dependency-analysis.md、references/language-migrations.md、references/safety-patterns.md、references/rollback-strategies.md。