用 Claude Code 做大规模代码迁移：Anthropic 的六步法，Bun 两周把一百万行 Zig 换成 Rust，以及动手之前要备齐的东西

这篇解决一个问题：整个代码库要换一门语言或者一套框架，以前要几年，现在怎么用 Claude Code 在几周里做完，而且做完了敢上线。

本站的《用 Claude Code 做重构和迁移》讲的是一个会话里的改动：plan 模式出计划，一步一个提交地改。这篇讲的是另一个量级：几十万到上百万行代码，几百个智能体分批并行，跑好几天。内容来自 Anthropic 的两篇文章，以及官方放出来的迁移工具包和代码现代化插件。本站没有实测，做一次这种量级的迁移，花费以万美元计。

一、两个例子

	Bun：Zig 换成 Rust	一个内部工具：Python 换成 TypeScript
谁做的	Bun 的联合创始人 Jarred Sumner，现在在 Anthropic	Anthropic Labs 的 Mike Krieger
规模	约一百万行，不到两周	16.5 万行 TypeScript，一个周末
怎么验收	合并前 Bun 原有的测试在 CI 里 100% 通过；合并后冒出 19 个回归，都已修好	8 道关卡、3 轮对抗式审查，最后把每条命令的输出和 Python 原版逐一比对
花了多少	59 亿不走缓存的输入 token、6.9 亿输出 token，按 API 价约 16.5 万美元	主体部分 2700 万 token
换来什么	测得出的内存泄漏全部修掉，一个重复构建 2000 次的测试内存从 6,745 MB 降到 609 MB；Linux 和 Windows 上的二进制小 19%；HTTP 和 next build、tsc 这类实际负载快 2% 到 5%。代价是约 4% 的代码在 unsafe 块里，多是和 C/C++ 交界处的单行指针操作	每个平台打包要 8 分钟、整套发布要等 30 分钟，换完以后打包约 2 秒，启动快 6 倍，还撤掉了一条单独的部署流水线

Bun 的 Rust 版 6 月起已经随 Claude Code 一起发布。Mike 的做法和 Jarred 不一样：他把整个迁移从头到尾跑完，看结果改规则和流程，再整个重跑，前两次的产出都扔掉，第三次才留下。

两个例子背后是同一句话：不修代码，修产生代码的那个流程。 某个文件翻错了，不去手改那个文件，而是找出是哪条规则缺了或错了，改规则，让受影响的那批文件重新生成。

二、值不值得迁

以前没人愿意做语言迁移，不是因为没好处，而是代价太大：几个季度冻结路线图，两套代码并行维护，最后只做到九成一致，比开始时还麻烦。现在最坏的结果是把分支删了重来。

但它仍然要有说得过去的理由。文章的估计：百万行的迁移不再是四年、三四百万美元的人力，但执行起来仍然要几万到几十万美元，甚至更多。好在理由不必是生死攸关：变更日志里一年都在补内存的 bug，或者一个长期卡脖子的瓶颈（Mike 那个就是打包太慢），就够了。

代码现代化那篇补了一个角度：多数公司做现代化，主要图的不是省钱，而是降风险。 跑在没人维护的运行时上、带着补不上的漏洞、懂这套系统的人越来越少，这些不迁的风险，要拿出来和迁的风险放在一起比。

先别急着动手。官方工具包的第一个提示词 prompts/00-feasibility.md 只读不写，出一份可行性报告：为什么要迁，三个必须先定的问题（照原结构翻还是重新设计、验证要花多少、现有的测试能不能带过去），按你的仓库写出六步的草图，最后给结论。“别迁”也是一个正常的结论。

JavaScript 换 TypeScript 一般用不着这一套。 TypeScript 是 JavaScript 的超集，可以一个文件一个文件地慢慢改，不用维护两套代码。这一套是给“每个文件都要换、老语言最后要删光”的情况准备的。

三、为什么这种活适合交给智能体

• 能并行。 几千个文件、包可以同时翻，不用互相等。
• 老代码就是需求说明。 新代码要做什么，老代码写得清清楚楚。
• 有现成的裁判。 测试套件能客观地判对错，智能体可以对着它连续磨好几天，不用人在旁边裁决。
• 待办清单自己会长出来。 编译器报的每个错、测试挂的每一条，都是下一个要修的。
• 偏差藏不住。 审查者指出问题时要说明违反了哪条规则，违规就成了一条待办；碰到边界情况，修法写成一条规则，后面的智能体都照着做。

两个例子都用 Fable 做关键的步骤，搭配几种不同级别的模型省 token，类似本站《advisor 工具》里讲的思路。并行调度用的是 Claude Code 的动态工作流。

四、动手之前：先有一个裁判

没有裁判，就没有“做完了”的标准。这个裁判要能用同样的标准评判老代码和新代码。问题在于，用老语言写的测试常常依赖内部函数，换了语言这些函数就不存在了。建裁判分三步：

1. 给现有的测试分类。 让 Claude 找出哪些测试是从外部调用的（命令行、接口、导出的函数），哪些依赖带不过去的内部实现。
2. 改写成两边都能跑的。 把从外部调用的那部分改成能同时对老代码和新代码跑的断言，再派对抗式的智能体检查改写有没有把断言改松。
3. 验证裁判本身。 先对老代码跑，必须全过；再对故意改坏的代码跑，必须报错。抓不住错误的裁判不算裁判。

Bun 运气好，原本就有一大套用第三种语言（TypeScript）写的测试。多数项目没有这个条件。Mike 的办法是自己搭一个“对照裁判”：7 个真实使用场景，每个都在新旧两边各跑一遍，比较结果，行为有任何不同都当 bug。

工具包里对应的是 prompts/00b-judge-setup.md。工具包自己说明，这个提示词还没有在任何一次试跑里用过，其中“拿故意改坏的代码验证裁判”这一步是新加的，从没跑过，它的产出要当草稿来调。工具包的三次试跑都是到最后一步才建裁判，结果第一次的对照裁判自己带着两个比较上的 bug（空白字符没处理好；JSON.stringify 把 NaN、-Infinity 变成了 null），报出 12 处“不一致”全是假的。所以它的建议是：先调试裁判，再相信它的结论；一个什么都判不过的裁判，多半是裁判坏了。

五、六步

第一步：规则手册、依赖图、差异清单

三样东西，一起做，一起审：

• 规则手册。 凡是翻译时可以有两种做法的地方，在这里一次定下来。工具包的说法是：两个智能体可能答得不一样的问题，就该写进规则手册。照原结构翻（Bun）时，它主要是一张对照表：老语言的类型和惯用法对应新语言的什么；重新设计（Mike）时，它是一份设计文档。Jarred 是和 Claude 一边聊一边把每个模棱两可的地方定成规则，又按自己的经验配了 8 个子代理，各查一类常见的错。
• 依赖图。 决定先翻哪些文件、哪些要放在同一批。有的语言有明确的依赖清单，C/C++、Python 这类往往要自己分析。要用确定性的脚本来做，不靠智能体判断。工具包里有 Python、JS/TS、C 头文件的依赖分析脚本。要同时看文件级和目标语言的包级：工具包的 README 提到，Bun 的文件依赖图很干净，但包级的循环依赖没人查，编译时冒出了约 1.6 万个错误。
• 差异清单。 新语言要求、老语言不要求的地方，逐处列出来。Zig 换 Rust，差在内存的所有权：Zig 里谁来释放一块内存往往只靠注释说明，忘了释放照样能编译；Rust 里所有权写在类型里，忘了、重复释放都编译不过。Python 换 TypeScript，差在接口：Python 函数接受什么形状的对象不用声明，TypeScript 必须先写出来。清单是一张平铺的表，翻译的智能体按需搜索，不用从头读到尾。

顺序上，规则手册要先于差异清单：差异清单记的就是规则手册的默认做法覆盖不到的地方。Jarred 是先列清单再翻译；Mike 是先翻译，再回头审出清单。可能两样都要做。

第二步：试航

规则手册还没碰过真代码。全面铺开之前，先做一次小规模的迁移，目的是改规则，不是推进进度，翻出来的文件全部扔掉。

Jarred 的做法：一个智能体照规则手册翻 3 个文件；另一个智能体“像一个资深的 Rust 工程师那样”翻 3 个文件；第三个智能体根据两份的差异写出新的翻译规则。这一步他抓到两个严重的问题，要是铺开到全部 1,448 个文件，会造成大量错误。

工具包把这一步写得更细：第二个翻译者在单独的上下文里，完全不知道有规则手册；看差异的智能体要把每一处差异都判成对某条规则的结论；改规则的建议先排队等你批准，不会自己改进规则手册。除了这场对比，工具包还要求按正式铺开时的流程原样试跑一小批难翻的文件，评的是守不守规矩，不是翻得好不好。

工具包的试跑也印证了这一点：一个 Python 小库的试航里，两份翻译有 14 处实质差异，规则对的 9 处、原生翻法对的 2 处、两边都说得过去的 2 处、两边都错的 1 处：照规则翻的那份，在 Python 会直接报错的地方悄悄输出了被破坏的数据，而且完全符合当时的规则。这次试航之后，规则手册加了 10 条修订。

这种对比只适用于照原结构翻的迁移，两份翻译才能逐行比。重新设计的话，对比测出来的是你的设计而不是规则，要换成：让对抗式的审查者直接挑设计文档的毛病，再用一次可以扔掉的端到端试跑验证。

第三步：全部翻译

从这一步起，每一步都是同一个循环：实现、审查、修。

• 实现用小模型，审查用大模型。 Mike 铺开主体迁移时派了 12 个用 Sonnet 的子代理。
• 待办队列要是机械的。 一个脚本看目标文件在不在磁盘上，判断哪些做完了，把没做的切成批次分给实现的智能体。队列每次都从磁盘重建，所以随时可以停、随时可以接着做。“做完”就是“输出文件存在”。
• 智能体会过于谨慎，做得太少。 办法是在提示词里直截了当地说清楚：下一步编译器会把错误抓出来，放手翻。
• 拿不准的地方打个标记。 翻译时没把握的写成 // TODO(port): <原因>，留给后面处理。
• 两个对抗式审查者，各用独立的上下文。 两人意见不一致时交给第三个智能体裁决。同一个错误在很多文件里反复出现，说明不是单个文件的问题：在规则手册里加一句话，重新生成受影响的那一批。规则手册在这一步一直在长，代码从来不针对它手工打补丁。

编译器放在哪，是这一步的一个关键决定。 Mike 每个循环里都跑 TypeScript 编译器，因为检查一个文件只要几秒；Jarred 干脆不让循环里跑编译器，留到下一步统一跑，因为 cargo 一跑就是几分钟。工具包的说法是：每个裁判都有价钱，价钱决定它放在循环的哪个位置。

工具包还给了一个 .claude/settings.json 模板，用配置禁掉而不是在提示词里请求：循环里的智能体不许跑编译器和测试，也不许用任何会改动仓库的 git 命令，status、diff、log 这类只读的留着，审查者要拿来取证；提交由负责调度的会话在每批结束时统一做。git reset、git checkout 的危险在于，十几个智能体共用一个工作区时，一个 reset 就毁掉其他所有人手上的活；翻好的文件在批次提交之前都是未跟踪文件，所以 git clean 最致命。工具包也说明，这些禁令是防止循环里误调用的护栏，不是安全边界，有心的包装脚本能绕过按模式匹配的规则。不让跑编译器还有一个更重要的原因：能编译的智能体会开始迁就编译器，不敢多翻。工具包的第三次试跑里，一个智能体想跑 cargo check 被拒，接着想改 settings.json 解除限制，又被 Claude Code 自身的保护挡住，最后按规定把问题交给了人。

到这一步，规则手册已经成了真正的提示词，开工的提示词反而很短。Bun 的“提示词”其实是一份 576 行的规则手册，加一句话的开工指令。

第四到六步：编译、跑起来、行为一致

三步用同一种循环，需要人判断的地方越来越少：

• 编译。 一个脚本对整个工作区跑一次编译，把错误清单切成队列，按模块从叶子往根排，修复的智能体并行处理，审查照旧是对抗式的。修完再整体编一次，直到没有错误。错误清单要有人看，用来发现系统性的问题。文章举的例子是：Bun 修掉循环导入（Zig 的惰性编译能容忍）之后，冒出几千个 Rust 模块错误，Jarred 的办法是在循环里加一段逻辑，判断每处依赖是该删、该挪，还是该重新划边界。如果目标语言的类型检查很便宜，这一步可以并进第三步。
• 跑起来。 先跑 hello world，再跑最小的端到端命令。冒烟测试里的崩溃按根因归类，交给审查者。
• 行为一致。 把第四节建好的裁判分片跑起来，修复的智能体对照新旧两边看失败的测试。工具包里有一个构建守护进程，只有它能重新构建：修复的智能体只写补丁，守护进程攒一批、构建一次、重跑受影响的测试、把结果送回去，免得几十个智能体各自触发最贵的那一步。同一种失败在很多测试里出现，就回到上游改规则，只重新生成那条规则涉及的文件。

Mike 没有能带到 TypeScript 的测试套件，就让 Claude 写了一个小脚本，在新旧两边跑 7 个真实场景并比较结果，每个失败的场景派一个修复的智能体，直到 7 个全过。他还让 Claude 自己设计一套端到端测试，连续四个晚上无人值守地跑、修、再跑，抓到了场景清单预料不到的小毛病。没有测试套件挡不住这一步：继承不到裁判，就让 Claude 造一个，老代码始终是标准答案。

工具包定义的“做完”：裁判里的测试全部通过，并且原来的测试在原来的代码上重跑一遍，没有原本就失败的。之后再用 prompts/06-post-parity.md 处理留下的 BUG(port)、TODO(port)、PERF(port) 标记，每处修复单独提交，用裁判重跑证明没改坏。

六、官方的迁移工具包怎么用

工具包在 GitHub 的 anthropics/code-migration-kit-with-claude-code，Apache-2.0 许可。它是文章所讲流程的通用模板，不是 Bun 和 Mike 实际用的那一套，也说明了只是参考代码，不积极维护，也不处理 issue 和 PR。默认针对照原结构翻的迁移。

里面有什么	用途
prompts/	8 个可以直接贴的提示词：00 可行性、00b 建裁判、01 依赖图、02 差异清单、03 试航、04 开工、05 统一编译、06 行为一致之后的收尾
templates/	规则手册、差异清单的模板，settings.json 和每条禁令的理由
scripts/	依赖分析（Python、JS/TS、C 头文件）、待办队列、清单生成、构建守护进程
skill/	一个按六步带你走的 Claude Code skill
examples/	一次完整试跑的产出：填好的规则手册、差异清单、对照报告
RUN-NOTES.md	工具包自己三次试跑的记录

用法按它的 README：

1. 把工具包克隆到要迁移的仓库里面或旁边。
2. 把工具包的 CLAUDE.md 复制或用 @ 引入到目标仓库的 CLAUDE.md，每个会话都会读它。
3. 可选：把 skill/ 复制到 ~/.claude/skills/code-migration，改掉里面的 [kit path]。
4. 在目标仓库里打开 Claude Code，填好占位符，贴 prompts/00-feasibility.md。
5. 第一步之前确认有裁判；没有就跑 prompts/00b-judge-setup.md。
6. 跑 prompts/03 之前（第二步的试跑就要禁令生效），把 templates/settings.json 复制到目标仓库的 .claude/settings.json。03 和 04 会检查它在不在，不在就停：一次早期试跑漏了这一步，整个过程都没有护栏，也没人发现。这份禁令一直用到第四步；要是类型检查便宜、想在循环里跑，到那一步删掉编译相关的几条；第六步修复时，再把禁跑测试的几条打开，只让构建守护进程重跑测试。
7. 按顺序跑 01 到 06，每过一道关卡，由你决定开始下一步。

“你批准”的方式，就是启动下一步：每个阶段跑完、交出证据、停下来；队列都按磁盘上的文件定义，停下来不花钱，接着做就是重新启动一次。

工具包的三次试跑：一个 1,425 行的 Python 库换成 TypeScript，12 个场景在 JSON 规范化之后和原版逐字节一致，子代理约用 110 万 token；一个约 730 行的 C 表达式解析器换成 Rust，原来的 4,930 个冒烟测试在原代码上重跑零失败，翻好的 11 个集成测试全过；同一个仓库再跑一次，专门走“编译器不进循环”那条路，第三步约 204 万 token、35 个智能体、21 分钟。每次试跑暴露出来的问题，都改进了工具包本身。

七、不是换语言，而是升级和现代化

代码现代化那篇写给关键系统和受监管的企业（比如银行），讲的是迁移开始之前组织上要做的事。它把现代化分成三种：

类型	是什么	什么时候选	对照什么
升级（uplift）	同一套技术升版本，比如 C++11 到 C++20	技术栈没问题，只是版本落后：运行时停止支持、漏洞补不上、依赖升不动	原来的代码，原来的测试可以当核心
转换（transform）	换技术栈、行为不变，比如 COBOL 到 Java	问题在技术栈，现有的行为是可信的	原来的代码，但老测试多半跑不了，靠回放生产流量、新旧对比、和生产并行部署
重塑（reimagine）	新架构重建，行为也要改	行为本身就要改	一份写下来、各方认可的行为说明，最难

到底做哪一种，组织里常有分歧：管生产的人想只换技术、行为不变，控制风险；天天和代码打交道的工程师想顺便还技术债，业务方想趁机提新需求。文章的建议是一开始就定下来，不然以后每次争论一个改动“对不对”，其实都是在争这个。

然后是两份事先写好、和审核的人一起约定的东西，再加上要备齐的前置条件：

• 合格证明。 每个改动必须满足的条件，每一条都能不靠人自动检查，智能体才能反复改到满足为止，满足不了就交给人。常见的条件：原有测试通过；迁移中写的新测试通过；覆盖率达到约定的线；性能在约定范围内；几个独立上下文里的 Claude 对抗式审查没有阻断问题；界面用 computer use 查过没有退化；同样的输入新旧两版输出一致；持久化的数据和传输格式在新旧之间来回转换不丢；在预发布环境跑够约定的时间没有异常；静态分析和安全扫描没有新发现。要和以后审核、合并这些改动的人一起写。 检验的标准是：他们是否愿意只凭这份证明就合并。
• 上线规则。 智能体出改动的速度远超人逐个审 diff 的速度。事先约定分级：按影响范围和智能体的把握分级，关键路径保留完整的人工审查；反复出现的同类问题，回到工作流或合格证明里修根源；审查的格式和审查的人一起定；领域专家的时间最稀缺，让他们直接看最高风险的那几级。在受监管的环境里，从轻审查会让签字的人不安，所以这条规则最好由公司高层定、事先约定，出了问题责任共担。
• 前置条件。 一台专门跑工作流的远程机器；合格证明需要的测试资源；依赖图；兼容性检查；原地做时冻结代码的约定，以及给其他开发者的通知；安全和合规：批准用于源代码的模型接入方式、工作流只能写迁移分支、不碰生产凭据、迁移分支里清掉密钥和个人信息、每个 PR 都能追溯到智能体的记录和证明、新依赖查许可证和漏洞。这些要其他团队配合，越早开口越好。

最后才是搭工作流和正式跑：先在一小块代码上从头到尾做完，包括按上线规则审核和合并，有问题趁便宜时修工作流，确认没问题再铺开。升级还可以在线上的代码库里原地做：从叶子往里分区，一次冻结并升级一个区，CI 里加检查，防止新提交把升级过的区改回去。

代码现代化插件

文章推荐用官方插件 code-modernization 起步：

/plugin install code-modernization@claude-plugins-official
/code-modernization:modernize

modernize 会问你几个问题，把答案写进 INTENT.md，给出第一条要跑的命令。也可以一步一步来：

步骤	命令	得到什么
1	modernize-preflight <名字> --source <代码路径>	环境是否就绪，问五个只有人能回答的问题，证明这份代码能构建
2	modernize-assess	清单、复杂度、技术债、安全问题，推荐一种做法
3	modernize-map	依赖、数据流、入口和业务流程的交互式地图
4	modernize-extract-rules	业务规则，写成 Given/When/Then，带 文件:行号，每条由第二个智能体复核
4b	modernize-review	人确认或改正看起来不对的规则
5	modernize-brief	分阶段的计划，批准之前什么都不构建
6	modernize-uplift、modernize-transform 或 modernize-reimagine	构建
7	modernize-verify	证明：干净地重跑测试、新旧两边同样的输入逐字节比较、至少十个新造的输入、故意改坏一行看测试会不会红，每个模块给出“已证明”“部分证明”“未证明”
8	modernize-harden	对老系统做安全扫描，给出你自己应用的补丁

它只往 analysis/ 和 modernized/ 里写，不改原来的代码；例外是构建检查，它会把构建产物写到原来构建默认的位置。建议在 .claude/settings.json 里用 deny 规则把这一点固定下来。deny 规则管得住 Claude 的文件工具和它认得的 shell 命令，管不住自己去开文件的脚本，所以 uplift 和 reimagine 里那两个同时派出很多写文件智能体的步骤，Bash 要保持逐次确认。

插件的说明里列了它试过的项目，多数是在一个模块上的试点：AWS 的 COBOL 示例程序 CardDemo 只把其中的月度计息作业改写成 Java 21，最后判定 NOT PROVEN；Jetty 只在 jetty-util 模块上从 Java 8 升到 17；一个 PHP 商城（osCommerce）只把商品页这一片改成 Python 和 FastAPI；Spring PetClinic 从 Spring Boot 2.6 升 3.3，停在了计划关卡，没有动手构建。

插件会通过 Claude Code 自己的遥测发一些整数计数（用了哪个命令、做到哪一步之类，不发代码、路径和提示词），不想发就设 CODE_MODERNIZATION_TELEMETRY=0，或者用 Claude Code 的 DISABLE_TELEMETRY=1。

用 claude -p 脚本化跑时，要设下面这个环境变量，不然无界面的会话 10 分钟后就不等后台的工作流了：

export CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0

官方的分工：迁移工具包针对整个代码库换语言；这个插件针对老系统的现代化和框架升级，也能一个模块一个模块地改写成别的技术。两样可以一起用。

八、几条经验

两篇文章和工具包反复强调的：

• 别照搬。 每次迁移都不一样，先和 Claude 一起针对你的代码库把流程定下来。
• 别盯着单个失败。 单个失败是循环的事；你的注意力放在反复出现的模式上。
• 审查要对抗，验证要机械。 让编译器、diff、测试套件当裁判。对抗式审查花 token，但值：工具包第一次试跑为了省钱跳过了每个文件两个审查者，结果一个跨文件的类型冲突漏到了编译那一步，正是审查本该抓住的那一类。
• 别什么都用最大的模型。 token 集中花在循环里。大批量的实现交给小模型，大模型留给审查和写规则。现代化那篇补了一句：可以在便宜的模型满足不了合格证明时升级到贵的，但试点时要算清重试率，几次便宜的尝试可能比一次贵的还贵。
• 人的时间花在前面。 规则手册和试航最费人的时间，之后基本是队列在烧。
• 审结果，不审代码。 你改的是循环，不是代码。

九、花费怎么估

• 工具包的建议：用看得见的乘法估，工作单元数乘以每个单元的估计，不要拍脑袋。乘数的大头是审查的结构，而试跑里抓到的问题也主要来自审查。
• 现代化那篇的建议：在一小块代码上做完整个流程，量出 token 用量，外推到全部，得到的是下限；试点看不到的部分（比如在线上的代码库里，和别人的提交对齐）算作未知。主要的成本因素：要读的代码和要改的代码各有多少；合格证明有多复杂（在受监管的环境里，验证往往比写改动花得多）；要写多少新测试、修多少旧测试；迁移期间别的团队在旁边合并了多少代码。
• 速率限制只影响日历，不影响能不能做：限额低，同样的步骤拉长时间而已。
• 参考数：Bun 约一百万行，按 API 价约 16.5 万美元。

本站没有实测

这一篇按两篇官方文章、工具包和插件的说明整理，本站没有实测：一次像样的迁移要几百个智能体跑几天，花费不是本站的测试额度承受得了的。文中的数字都出自官方文章和工具包的试跑记录。

参考

• How Anthropic runs large-scale code migrations with Claude Code（Claude 博客，2026-07-16）
• Jonah Ezekiel、Lexie Tonelli：How to prepare for AI-driven code modernization projects（Claude 博客，2026-09-23）
• Claude Code Migration Kit（GitHub）：README、RUN-NOTES.md、templates/settings.README.md
• Code Modernization 插件（GitHub）：README