Anthropic 用 Claude Code 大规模迁移代码：Bun 百万行 Zig 转 Rust，两周完成

使用 AI 代理进行大型代码迁移的逐步指南 —— 包括 Bun 的百万行 Zig 到 Rust 的移植。

代码迁移，即将生产代码库迁移到新语言的项目，直到最近仍然是多年的工作。

在过去一个月里，Anthropic 的独立开发者使用 Claude Fable 5、Claude Opus 4.8 以及动态工作流程迁移了 10 个代码包，总计数十万到数十万行代码：https://claude.com/blog/introducing-dynamic-workflows-in-claude-code。在本文中，我们将介绍两个示例以及这些项目的最佳实践。

Bun 的联合创始人以及 Anthropic 技术员工 Jarred Sumner 使用 Claude Code 将 Bun 从 Zig 迁移到 Rust：https://bun.com/blog/bun-in-rust。不到两周的时间就生成了百万行代码，在合并前 Bun 现有的测试套件在 CI 中全部通过。合并后出现了 19 个回归问题，目前全部已修复。Rust 版本在 6 月通过 Claude Code 发布。

Anthropic Labs 的联合负责人 Mike Krieger 在一个周末将一个 Python 代码库迁移到 165,000 行的 TypeScript。这包括数百个代理、八个阶段门、三轮对抗性审查，以及最后一次比对检查，将每条命令的输出与原 Python 版本进行差异对比。

Claude Code 的新功能改变了这些长期拖延项目的计算方式。下面是我们现在使用的六步流程，总结自这些迁移项目的经验。

核心见解是你不修复代码，而是修复生成代码的过程（循环）。

在直接讨论如何做之前，值得讨论一下何时以及为什么，因为这些项目的假设已发生变化。

团队发起迁移是因为从初始构建到当前项目之间的环境发生了变化。要么已知的权衡变得受限，要么出现了更好的方法，或者原来的生态系统正在萎缩。

例如，Jarred 最初选择 Zig 是因为它提供了 C 级性能并且极其简洁，非常适合一个创始人在没有 LLM 帮助的情况下“在奥克兰狭小公寓中用一年时间编写 Bun”。这种简洁性伴随着已知的权衡，他在这里进行了说明：https://bun.com/blog/bun-in-rust#just-be-really-smart-and-don-t-make-mistakes.

快进到2026年。Bun 的 CLI 每月下载量超过 1000 万次，并在 Claude Code 中被广泛使用。

就在上个季度，这些权衡可能还不足以证明冻结路线图并投入资源进行一个多季度项目是合理的。迁移语言可以带来更小、更快、更安全的系统，但没有人愿意为此付费。

软件工程师还必须应对这些曾经的超大型项目固有的职业风险。你可能需要维持两个平行的代码库几个月甚至几年，如果最终结果只有 90% 的一致性，你会比开始时面临更多的麻烦。

现在，最坏的情况就是删除分支然后重新尝试。

仍然需要有合理的商业案例。虽然百万行级别的迁移不再需要在四年项目周期内花费 300 万到 400 万美元的工程资源，但执行仍然需要花费数万到数十万美元甚至更多。例如，Bun 的迁移消耗了 59 亿未缓存输入令牌和 6.9 亿输出令牌——按 API 定价约为 16.5 万美元。Mike 的迁移的主要部分是 2700 万令牌。

然而，迁移案例不再需要是生死攸关的。一年的内存错误修补记录，或一个长期存在的瓶颈，现在就足以证明迁移的合理性。

编译步骤是 Mike 项目的动力。他团队使用的内部工具作为单个二进制文件发布给用户。使用 Python 工具链生成该二进制文件每个平台大约需要八分钟，总计在每次发布的构建矩阵上等待 30 分钟。迁移后，同样的编译现在大约只需两秒，二进制启动速度提高了 6 倍，团队还能够淘汰一个单独的部署流水线。

Claude Fable 5 是我们最强大、可广泛使用的模型。Fable 和 Opus 4.8 在分配、指导、验证基于子代理的并行工作流方面表现尤为出色，同时能够找到多个方式实现既定目标。

大型代码迁移是这些高级模型特别有效的使用场景，因为：

正如我们下面将看到的，Mike 和 Jarred 在迁移过程中关键步骤都使用了 Fable，特别是在使用多模型类来优化令牌消耗的 advisory 模式中。

下面的过程已经被泛化，以适用于多种语言和场景。欲了解更多详情，你可以阅读 Jarred 的博客：https://bun.com/blog/bun-in-rust。

在开始迁移项目之前的先决条件是必须有一个强大的评判机制，否则你将没有退出条件或成功衡量标准。

评判者必须能够在相同条件下评估原始代码和目标代码。原语言编写的测试套件通常依赖于目标代码中不存在的内部函数。

Jarred 有一个用第三种语言（TypeScript）编写的大型测试套件，但大多数项目并非如此。对于他的 Python 到 TypeScript 移植项目，Mike 创建了一个包含七个真实场景的对等测试框架，并将任何行为变化都视为需要修复的漏洞。

在进入每个阶段之前，这张图表可能有助于你跟随理解。这主要遵循 Jarred 的方法论，每个阶段都有评审和关卡。Mike 也遵循了类似的整体结构，使用类似的循环工作流，但他从头到尾运行了整个迁移，基于结果修改规则和工作流，然后再次运行——每次丢弃输出，直到第三次运行。

在这一阶段，我们正在创建迁移的基础：一份代码需要重构而不仅仅是翻译的地点清单，一本代码翻译规则手册，以及一张依赖关系图，用来安排迁移实施流程。

顺序很重要：规则手册必须在差距清单之前。差距清单是由规则手册的默认设置无法涵盖的部分定义的，这两项将在联合审核中一起测试。

规则手册的具体形式：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/templates/RULEBOOK.md 取决于你在开始时必须做的关键架构决策。其中最重要的是，新代码是否会沿用相同结构，还是会完全重新设计。

如果是前者（Jarred），规则书主要是查找表，将不同语言之间的类型和习语进行转换，同时指向更难翻译组件的差距清单。如果是后者（Mike），它将是一个设计文档。

Jarred通过与Claude聊天创建了他的规则书，为每个模糊的区域制定策略。他还使用了八个专门设计的子代理，针对他直觉中常见失败模式的八个不同类别进行检查。

你需要了解文件依赖关系，以便有效地拆分工作流以进行并行迁移，这样你就知道哪些文件应首先迁移，哪些文件应包含在同一批次中。一些语言和代码库有明确的清单，使此操作变得容易，但对于遗留代码库和许多流行语言如C/C++和Python，这些依赖关系需要被发现和映射。

Claude Code可以部署代理来创建并运行确定性脚本以生成此映射。迁移工具包中的提示：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/prompts/01-dependency-map.md 使用一个工作流来创建审查和修正循环。注意：启动套件是本文概述过程的通用模板——并不是这些特定迁移所使用的工具。

新语言有不同于旧语言的要求，必须满足这些要求。对于Zig到Rust的迁移，差异在于手动内存管理（C和C++的工作方式相同）。例如：

对于Python到TypeScript的迁移，差距在于接口和合同。Python不要求声明接受何种形状的对象或返回什么，但TypeScript则要求。例如：

Jarred和Mike都创建了捕获这种隐含知识的差距清单文件。Jarred预先盘点了这些差距，这也是我们在此处所做的，而Mike选择先翻译，再通过审核创建差距清单。你可能需要两者兼做。

查看这个Claude Code示例提示以创建差距清单文件：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/prompts/02-gap-inventory.md。

这一步涉及一个迷你迁移，作为更大规模迁移的“试航”。

在这一步中，Jarred 使用一个代理通过规则书翻译三个文件，另一个代理以“高级 Rust 工程师”的方式翻译三个文件，还有一个代理使用差异创建新的翻译规则。在这个阶段，他发现了两个关键问题，如果扩展到所有 1,448 个文件，可能会造成大量问题。

提示可能类似于这个：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/prompts/03-stress-test.md。

这种类型的压力测试仅适用于结构保持迁移，其中同一个文件的两种翻译可以逐行比较。如果你的规则书是重新设计——像 Mike 的那样——等价的测试方法是用对抗性的评审直接攻击设计文档，然后通过一次可丢弃的端到端运行进行验证。

无论如何，请丢弃任何已经翻译的文件。目标是优化规则，而不是取得渐进性的进展。

在接下来的步骤中，你将运行相同的多代理循环架构：实现、审查和修复。

你可以将实现者的工作卸载给较小的模型，同时让评审者使用较大的模型。例如，Mike 在主迁移过程中扩展 12 个子代理时使用了 Claude Sonnet。

工作队列应当是机械化的。批处理脚本通过检查磁盘上是否存在已翻译文件来决定已完成的任务，然后将待处理文件切分为实现者代理的批次。因为队列每次都是从磁盘重建的，所以迁移从设计上是可恢复的。

在这一阶段，代理可能对执行工作量过于谨慎。解决方法可以是一个直接、有力的提示指令，并附带上下文，让编译器在下一步捕捉错误。

任何翻译者不能自信执行的事项都会被标记为 // TODO(port)：在步骤 4 中处理。从此以后，代办列表会自动生成：编译器列出错误，烟雾测试发现崩溃，测试套件报告失败。

两个对立的审阅者使用不同的上下文来评估实现者的工作，如果审阅者之间有分歧，则交给第三个代理处理。当一个审阅者在多个文件中反复发现同样的错误时，修复不是按文件进行的。你在规则书中添加一句话，然后重新生成受影响的批次。通过这一步，规则书持续增长；代码从未针对它进行手工修补。

在此步骤中需要注意的一个重要设计决策是编译器的位置。Mike 在每个循环中运行 TypeScript 编译器，因为它可以在几秒钟内检查一个单元。Jarred 完全禁止在循环中调用编译器，而将其推迟到下一步，因为 cargo 需要几分钟。

此步骤中，大部分繁重的工作已经完成，提示语开始变得更短。：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/prompts/04-translation-kickoff.md

这三个步骤共享相同的循环架构，并且需要逐渐减少人的判断，因此我们一起介绍它们。

例如，第 4 步可能经常根据迁移的语言和规模而演变成第 3 步。

根据编译器步骤的规模和难度，代理可能根本不运行这一阶段。Jarred 使用一个编排脚本执行此步骤，该脚本在整个工作区只调用一次编译器。“修复代理”然后与对立审查一起并行处理错误列表。然后再次运行构建，反复如此。

查看错误列表有助于捕捉可能需要调整的系统性问题。例如，Jarred 在修复 Zig 的惰性编译可以容忍的循环导入后，遇到了成千上万的 Rust 模块错误。他通过编码逻辑来分类哪些依赖需要删除、移动或重构边界，从而修复了循环。

第 5 步同样有一个类似于编译器错误列表的机械事实来源：冒烟测试崩溃。同样，循环修复是将问题分组，在此案例中按根本原因分组，由对立子代理进行审查。

第 6 步，也是我们故事的结尾，是比较两个代码库中的程序行为。

我们的文件现在已经被翻译、编译并进行了冒烟测试。现在是时候将它们分片并对它们运行测试套件（来自前置阶段）。使用“修复代理”处理失败，这些代理会对比两个代码库来审查失败的测试。对抗性审查员会检查他们的修复。

这个循环的下一阶段是构建守护进程：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/scripts/build_daemon.sh，这是唯一被允许重建二进制文件的进程。修复者编写补丁；守护进程将它们批处理，重建一次，重新运行受影响的测试，并反馈结果。这将最昂贵的操作串行化，而不是让多个代理独立触发它。

当同一个失败在许多测试中重复出现时，修复会向上游移动：你修改导致错误的规则，并只重新生成该规则触及的文件。

Mike的方法在这里很重要，因为许多开发者没有完整或移植的测试套件。Mike让Claude创建了一个小脚本，对新的移植版本和原始Python代码库运行7个真实场景，并对结果进行差异对比。每个失败的场景都有自己的修复代理，循环运行直到七个场景全部通过。

然后他更进一步。Claude设计了自己的端到端测试套件，并在整夜运行时自动修复出错部分，并连续四个晚上重新运行。因此，它捕捉到了任何场景列表都无法预测的细微问题。

A step-by-step guide to running large code migrations with AI agents — including Bun's million-line Zig-to-Rust port.

Code migrations, projects that port a production codebase to a new language, were multi-year endeavors until recently.

In the last month, individual developers at Anthropic migrated 10 code packages consisting of tens to hundreds of thousands of lines of code using Claude Fable 5, Claude Opus 4.8, and dynamic workflows：https://claude.com/blog/introducing-dynamic-workflows-in-claude-code. In this article we’ll cover two examples along with best practices from these projects.

Jarred Sumner, co-founder of Bun and Member of Technical Staff at Anthropic, used Claude Code to migrate Bun from Zig to Rust：https://bun.com/blog/bun-in-rust. A million lines of code were produced in less than two weeks, with 100% of Bun's existing test suite passing in CI before merge. Nineteen regressions surfaced after merge and have all been fixed. The Rust port was shipped inside Claude Code in June.

Mike Krieger, co-lead of Anthropic Labs, migrated a Python codebase to 165,000 lines of TypeScript over a weekend. This included hundreds of agents, eight phase gates, three adversarial review rounds, and a final parity check that diffed every command's output against the Python original.

Claude Code’s new capabilities change the math for these long-deferred projects. Below is the six-step process we now use, drawn from what these migrations taught us.

The core insight is that you don’t fix the code. You fix the process (loop) that produced the code .

Before going straight into the how , it’s worth discussing the when and why because the assumptions around these projects have evolved.

Teams launch migrations because of landscape changes between their initial build and current project. Either a known trade-off has become limiting, a better approach has emerged, or the original ecosystem is shrinking.

For example, Jarred originally chose Zig because it offered C-level performance with radical simplicity, ideal for a solo founder “writing Bun in 1 year in a cramped Oakland apartment pre-LLM.” This simplicity came with known tradeoffs, which he writes about here：https://bun.com/blog/bun-in-rust#just-be-really-smart-and-don-t-make-mistakes.

Fast forward to 2026. Bun's CLI is getting over 10 million monthly downloads and is used extensively within Claude Code.

As recently as last quarter, those tradeoffs wouldn’t have been enough to justify freezing the roadmap and committing resources to a multi-quarter project. Migrating languages can deliver smaller, faster, and safer systems, but no one wants to pay for them.

Software engineers have also had to contend with the career risk inherent in these formerly mega-projects. You could maintain two parallel code bases for quarters or years, and if the end result was 90% parity, you had a bigger headache than when you started.

Now, the worst case scenario is you delete the branch and try again.

There still needs to be a justifiable business case. While million line migrations no longer cost $3 to $4 million in engineering resources over the course of a four year project, they still cost tens to hundreds of thousands of dollars or more to execute. The Bun migration, for example, consumed 5.9 billion uncached input tokens and 690 million output tokens — around $165,000 at API pricing. The main portion of Mike’s port was 27 million tokens.

However, the migration case no longer needs to be existential. A year of memory-bug patches in the changelog, or one chronic bottleneck, can now justify it.

The compile step was the impetus for Mike's project. The internal tool his team works on ships to users as a single binary. Producing that binary with the Python toolchain took roughly eight minutes per platform, totaling a 30-minute wait across the build matrix on every release. After the port, the same compile now takes about two seconds, the binary starts 6x faster, and the team was able to retire a separate deployment pipeline.

Claude Fable 5 is our most capable, generally available model. Fable and Opus 4.8 are particularly good at delegating, directing, and verifying parallel workstreams with subagents while finding multiple paths towards stated goals.

Large code migrations are a particularly effective use case for these advanced models because:

As we will see below, both Mike and Jarred used Fable for key steps in their migration process, particularly in an advisory pattern that used multiple model classes to optimize token consumption.

The process below has been generalized to be relevant to multiple languages and scenarios. For additional details, you can read Jarred’s blog ：https://bun.com/blog/bun-in-rust .

A prerequisite before starting on your migration project is to have a strong judge in place, otherwise you won’t have an exit condition or measure of success.

The judge must be able to evaluate both the original code and the target code on equal terms. Test suites written in the original language will often depend on internal functions that won't exist in the target code.

Jarred had a large test suite written in a third language (TypeScript), but that will not be the case for most projects. For his Python-to-TypeScript port, Mike created a parity harness of seven real-world scenarios and considered any behavior change a bug to be fixed.

Before we get into each stage, this graphic may help you follow along. This mostly follows Jarred’s methodology, with reviews and gates at each stage. Mike followed a similar overall structure using similar loop workflows, but he ran the entire migration end to end, revised the rules and the workflow based on the results, and ran it again — discarding the output each time until the third run.

In this stage we are creating the foundations of our migration: an inventory of places where code will need to be refactored rather than just translated, a rulebook for how to translate our code, and a dependency map to order our migration implementation workstreams.

The order matters: the rulebook must come before the gap inventory. The gap inventory is defined by what the rulebook's defaults won't cover, and the two are tested together in a joint audit.

The exact shape of the rulebook：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/templates/RULEBOOK.md depends on key architectural decisions you must make at the start. Chief among them, if the new code will follow the same structure, or if it will be completely redesigned.

If it’s the former (Jarred), the rulebook will primarily be lookup tables that translates types and idioms between languages while pointing to the gap inventory for the harder-to-translate components. If it’s the latter (Mike), it will be a design document.

Jarred created his rulebook by chatting with Claude, forming a policy for each area of ambiguity. He also used eight subagents specifically designed to review for 8 different categories of common failure modes based on his own intuition.

You need to understand file dependencies to effectively break up workstreams for a parallel migration so you know which files to migrate first and which files to contain in the same batch. Some languages and codebases have explicit manifests that make this easy, but for legacy codebases and many popular languages like C/C++ and Python, these dependencies need to be discovered and mapped.

Claude Code can deploy agents to create and run a deterministic script to produce this map. The prompt in the migration kit：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/prompts/01-dependency-map.md uses a workflow to create a review-and-fix loop. Note: The starter kit is a generalized template of the process laid out in this post — it's not what these specific ports ran on.

The new language has different requirements from the old language that must be met. For Zig to Rust the difference was manual memory management (C and C++ work the same way). For example:

For Python to TypeScript the gap was interfaces and contracts. Python doesn’t require a contract declaring what shape of object it will accept or what it returns, but TypeScript does. For example:

Both Jarred and Mike created gap inventory files capturing this implicit knowledge. Jarred inventoried these gaps up front, which is what we do here, while Mike chose to translate first and then create the gap inventory by auditing afterwards. You may need to do both.

Check out this sample Claude Code prompt to create a gap inventory file：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/prompts/02-gap-inventory.md.

This step involves a mini-migration that serves as a “shakedown cruise” for the larger migration.

In this step, Jarred used one agent to translate three files using the rulebook, one agent to translate three files “like a senior Rust engineer,” and one agent to use the diff to create new translation rules. At this stage he caught two critical issues that would have created numerous issues if fanned out across all 1,448 files.

The prompt may look something like this：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/prompts/03-stress-test.md.

This type of stress test only works for structure-preserving migrations , where two translations of the same file are comparable line by line. If your rulebook is a redesign — like Mike's — the equivalent test is attacking the design document directly with adversarial reviewers, then validating it with a disposable end-to-end run.

Regardless, throw out any translated files. The goal is to refine the rules, not make incremental progress.

For the remaining steps, you run the same multi-agent loop architecture: implement, review, and fix.

You can offload implementer work to smaller models and keep reviewers on larger ones. For example, Mike used Claude Sonnet when he fanned out 12 subagents for the main migration.

The work queue should be mechanical. A batch script decides what’s done by checking whether the translated file exists on disk, then slices the pending files into batches for the implementer agents. Because the queue is rebuilt from disk every time, the migration is resumable by construction.

At this stage, agents can be overly cautious with how much work they do. The fix can be a blunt, emphatic prompt instruction with context that the compiler will catch mistakes in the next step.

Anything the translator can’t execute confidently gets flagged with // TODO(port): to be dealt with in step 4. From here on, the to-do lists write themselves: the compiler enumerates the errors, the smoke tests find the crashes, the suite reports the failures.

Two adversarial reviewers evaluate the work of the implementers using separate contexts and disagreement between reviewers goes to a third agent. When a reviewer keeps catching the same mistake across files, the fix isn't per-file. You add one sentence to the rulebook and regenerate the affected batch. The rulebook keeps growing through this step; the code never gets hand-patched against it.

One important design decision to note in this step is where the compiler sits. Mike ran the TypeScript compiler inside every loop, because it checks a unit in seconds. Jarred banned the compiler from the loop entirely and deferred it to the next step, because cargo takes minutes.

At this step, much of the heavy lifting has been done and the prompts start to get shorter.：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/prompts/04-translation-kickoff.md

These three steps share the same loop architecture and need progressively less human judgment, so we cover them together.

Step 4 , for example, may often dissolve into step 3 depending on the language and size of the migration.

Depending on the size and difficulty of the compiler step, agents may not run this at all. Jarred executed this with an orchestrator script that invoked the compiler once across the whole workspace. “Fixer agents” then ran through the error list in parallel with adversarial review. The build runs again, rinse and repeat.

Reviewing the error list is helpful to catch systemic issues that may require adjustments. For example, Jarred ran into thousands of Rust module errors that surfaced after fixing cyclic imports that Zig's lazy compilation tolerated. He fixed the loop by encoding logic to classify which dependence to delete, move, or restructure the boundary.

Step 5 also has a mechanical source of truth similar to the compiler error list: crashes from the smoke test. Again, the loop fix was to group issues into categories, in this case grouping causes by root cause that are reviewed by adversarial subagents.

Step 6 and the end of our story is comparing the programs’ behavior across the two codebases.

Our files have now been translated, compiled, and smoke tested. Now it's time to shard them and run the test suite (from the prerequisite stage) against them. Tackle failures with "fixer agents" that review the failed tests against both codebases. Adversarial reviewers check their fixes.

The next stage in this loop is a build daemon：https://github.com/anthropics/code-migration-kit-with-claude-code/blob/main/scripts/build_daemon.sh, which is the only process allowed to rebuild the binary. Fixers write patches; the daemon batches them, rebuilds once, re-runs the affected tests, and feeds the results back. This serializes the most expensive operation instead of letting multiple agents trigger it independently.

When the same failure repeats across many tests, the fix moves upstream: you amend the rule that produced the bug and regenerate only the files that rule touched.

Mike's approach matters here, because many developers won't have a built-out or ported test suite. Mike had Claude create a small script to run 7 real-world scenarios against both the new port and the original Python codebase, and diffed the results. Each failing scenario got its own fix agent, and the loop ran until all seven passed.

Then he went one step further. Claude designed its own end-to-end test suite and ran it autonomously overnight, fixing what broke and re-running four nights in a row. As a result, it caught the paper cuts no scenario list would have predicted.