Migrating Millions of Lines of Code with Claude Code: A Step‑by‑Step Guide

Background and Motivation

Anthropic recently published a blog post describing how they used Claude Code to perform large‑scale code migrations. Two striking examples are highlighted: Bun’s founder Jarred Sumner rewrote the entire Bun codebase (≈530 000 lines) from Zig to Rust in 11 days with 100 % test pass, and Anthropic Labs co‑lead Mike Krieger migrated a Python project (≈165 000 lines) to TypeScript over a single weekend, cutting build time from 30 minutes to about 2 seconds.

Core Idea: Focus on the Migration Process, Not Manual Edits

Traditional migration translates file‑by‑file and fixes bugs individually, which quickly becomes infeasible for thousands of files. The recommended approach is to treat migration as a workflow: when Claude repeatedly makes the same mistake, update a shared rule handbook instead of fixing each occurrence.

Six‑Step Migration Method (Anthropic’s Blueprint)

Establish a Reliable Verification Mechanism – Ensure you have a test suite that can run independently of the source language. If tests are written in the same language as the source, categorize them into external‑behavior tests (reusable) and internal‑implementation tests (rewrite in a language‑agnostic form). Mike Krieger created a comparison script that runs seven real‑world scenarios and diffs Python vs. TypeScript outputs.

Define Rules Handbook and Dependency Graph – Spend the most manual effort here. Jarred spent three hours with Claude to produce a 576‑line rule handbook mapping Zig constructs to Rust equivalents, plus a LIFETIMES.tsv file describing struct lifetimes. Mike’s handbook was a design document for a new architecture. A dependency graph determines migration order and batch grouping.

Small‑Scale Pilot Run – Translate only three files first. Jarred ran two Claude agents in parallel (one following the handbook, another acting as a senior Rust engineer) and used a third agent to compare outputs and extract new rules. Mike ran multiple Claude agents to critique the design from different angles. Issues discovered are added to the handbook before full‑scale migration.

Full‑Scale Translation – Deploy a pipeline with three agents: a translation agent, a “find‑bugs” agent, and a repair agent. Each translated file is checked by two independent find‑bugs agents, which then hand off problems to the repair agent.

Iterative Compile‑Fix‑Test Loop – Compile the whole project, collect all compiler errors into a list, and let parallel repair agents fix them. Repeat until compilation succeeds. Jarred used 64 repair agents; Mike used 12 Sonnet agents for parallelism.

Run Tests and Align Behavior – Split the test suite, run failing tests, generate a fix list, and let repair agents address each failure, followed by adversarial review. This loop continues until no test failures remain.

Practical Insights and Costs

Adversarial review (having a separate agent assume the code is buggy) dramatically improves bug detection.

The Bun migration cost roughly $165 000 in Claude API usage, which is cheaper than three senior engineers for a year.

Even personal developers can afford migrations of tens of thousands of lines with a Pro or Max Claude subscription.

Human judgment remains essential: monitoring workflow output, adjusting rules, and making architectural decisions.

Takeaway Checklist

Before any sizable refactor, create a rule document with “what to change and how”.

Run a pilot on a few files, capture recurring mistakes, and update the handbook.

Separate the code‑generation AI from the code‑review AI (e.g., use Claude’s /code-review command or a dedicated sub‑agent).

Treat compilation errors, test failures, and lint warnings as task lists for the AI to fix.

With a well‑designed process, AI can handle migrations of hundreds of thousands or even millions of lines, making large‑scale refactoring feasible for most teams.