Vue 2 升 3、React class 转 hooks、JS 转 TS、Next.js Pages Router 转 App Router——这种大迁移过去要 3 周机械工作 + 1 周 bug hunt。让模型”把整个 repo 迁了”会得到一份看着像、跑不动的代码。这篇给工程师一套结构化 prompt 工作流，把 AI 的机械速度和你的 code review 判断结合，把一个真实迁移从 3 周压到约 3 天，并保持测试常绿。
这篇主要解决什么问题
AI 一口气搞大迁移会产出看着像但跑不动的代码。下面这套把工作切成”已验证的块”：1 个手工参考文件、模式扩散、长尾 codemod、对照官方 checklist 收尾。每块都有清晰的过/不过；失败止于一个文件，不是整个 repo。
这篇适合谁看
面对多周迁移、想让 AI 干机械活但又不希望它产出垃圾的开发者。最适合 50-1000 文件的代码库——手迁太慢、纯 codemod 漏判断 case。给迁移做预算的 tech lead 也受益——这套工作流让估算落地。
什么时候适合用
有官方升级路径的迁移（Vue / React / Next.js / Angular / Svelte），且多个文件共享同样的迁移模式。类型语言迁移（JS→TS、Python 2→3）也合适——有官方 codemod 但仍需判断清理。触发点：能点出 3 个文件，它们应该用同样方式被改。
什么时候不建议用
范式根本不同的迁移（jQuery → React、REST → GraphQL）AI 没法机械翻译，只能当学习辅助——架构决策是你的。代码库没有测试覆盖也不要上——任何迁移步骤都没法验证。
开始前准备
- 测试覆盖率确认 > 50%。没测试每一步迁移都是赌。覆盖率低就先给最常改的文件补 characterization 测试。
- 锁版本区间。“Vue 2.7 → Vue 3.4”和”Vue 2.0 → Vue 3.4”不同。模型需要确切起点。
- 把官方迁移指南从头到尾读一遍。AI 能总结，但你得能识别错误总结。
- 准备一条干净分支，没有其他重构并行。混着别的改动会让 bisect 失效。
具体步骤
- 第一次对话：让模型总结目标版本对的官方迁移指南。列 5-10 个最常见的机械改动。把官方 URL 一起放进 prompt——把模型锚定在官方路径，不是 2 年前的博客。
- 第二次对话：挑一个文件。中等复杂度、代码库中部的，不要最简单的。prompt：
对这个文件应用迁移改动 1-5。输出：
1. 迁移后的整文件
2. 与原文件的 diff
3. 你做出的所有判断 call
不要重构无关代码。不要改不需要改的变量名。不要"顺手优化"。- 逐行 review diff。只跑这个文件的测试。自己或再来一条聚焦 prompt 修问题。这文件就是你的参考实现。commit 之。
- 第三次对话：“这是 A 文件的参考迁移（贴）。用同样模式迁 B 文件（贴）。完全匹配 A 文件的迁移风格。”
- 手动 + AI 辅助迁 5-10 个文件。到第 3 个你已理解模式；到第 7 个你能 5 秒识破 AI 的错误建议。每个文件单独 commit，bisect 才好用。
- 长尾（40-200 个琐碎 case）：AI 帮你写一个 codemod。jscodeshift / ts-morph / AST-grep 是合适的工具。dry-run 看 diff 再应用。每批 codemod 后测试必须绿。
- 收尾：让 AI 对照官方 checklist 审整个迁移分支。prompt：“review 这个分支看是否漏了官方迁移条目：[贴 checklist]。“
第一次实操怎么跑
- 路线图里最小的非平凡迁移先做——可能是一个 feature 文件夹、10-20 个文件。真上线、爆炸半径小。
- 完整跑一次：官方指南摘要、参考文件、扩散、codemod、收尾审。每阶段计时。
- 把参考文件的 diff 和 codemod 脚本存下来。下一个同类型迁移的模板。
- 下次只改一个变量：换模型或一次 AI 扩散更多文件。
完成后检查
- 每次 commit 后测试都绿。一个 commit 改 5 个文件，先单独定位坏的那个再继续。
- 参考文件的 diff 10 分钟内能 review 完。超时说明模型加太多，把 prompt 加严”禁止无关改动”。
- codemod 的 dry-run diff 30 分钟内能 review 完。超时说明 codemod 太激进。
- 收尾审漏掉的条目 < 5 项。超过说明扩散中间有地方静默断掉，回去找差异点。
怎么复用这套流程
- 指南摘要 prompt、参考文件 prompt、扩散 prompt 存项目文档。下一个迁移换 URL 就行。
- 维护 MIGRATION-LOG.md（文件、状态、备注、blocker）。迁移被生活打断一周后，靠它重启。
- 建个内部 codemod 库。跨项目同样的模式反复出现（class→hooks、prop 改名、默认导入转命名）——写一次反复用。
建议的操作流程
官方指南摘要 → 1 个手工 + AI 参考文件 → 8 个按参考模式做 → codemod 处理 40 个琐碎 case（jscodeshift / ts-morph / AST-grep，先 dry-run）→ 收尾对 checklist 审 → 打 release tag。React class→hooks 约 50 个组件，3 天 vs 3 周。
容易踩的坑
- 一口气迁整个代码库。一面墙改动没法测、没法 bisect。
- 不写参考实现就开始。每个文件做法不同，reviewer 拒 PR。
- 不 dry-run 就跑 AI codemod。它常常顺手改无关代码。
- 文件之间不跑测试。错误会静默累积。
- 迁移和 feature 工作混在一起。坏了之后你分不清是哪个 commit。
- 用错模型。模型训练时间早于框架迁移指南发布的，会给过时建议。
进阶技巧
- 每个 prompt 都钉上官方迁移指南 URL——锚定官方路径而不是 2 年前博客。
- 大批量改名（useEffect 参数、prop 名、废弃生命周期）：grep + 脚本编辑比 AI 准。
- 维护 MIGRATION-LOG.md 记每个文件、状态、备注。被打断后能恢复。
- 团队迁移：参考文件先走团队常规 code review 再扩散。文件 1 抓到的分歧能省下文件 30 的 50 条评论。
- codemod 阶段设”不带判断”规则。codemod 不能机械决定的留 TODO 手工 review。
怎么验收输出
- 参考实现文件做完且测试通过。
- 后续每个文件匹配参考模式。
- codemod（如果有）dry-run review 通过再应用。
- 每次 commit 测试都绿，不只是末尾。
- 收尾 review 确认 checklist 全部覆盖。
- MIGRATION-LOG.md 已 commit，今天停下队友也能接手。
FAQ
- codemod 还是 AI 按文件？: 机械量大用 codemod；要判断的部分按文件让 AI 做。
- 真实迁移多久？: 看体量——AI 把机械 70% 减半，需要判断的 30% 时间还是要花。
- 哪个模型最适合做迁移？: 任何前沿、长上下文的模型。同时把参考文件 + 目标文件喂一次 prompt，迁移收益最大。
- 测试要同时迁吗？: 测试和源文件同步迁。测试和源代码分叉是迁移停摆的常见原因。
- 官方指南不完整怎么办？: 去框架 GitHub issues 搜迁移 tag。真实 edge case 住在 issues 不住在指南。
- 怎么 review 50 个 AI 迁的文件？: 按模式分组。共享同迁移模式的文件作为一批，详读 2 个、扫读其余。