← All posts

How Do I Migrate a Large Codebase With Claude Code?

Large migrations fail when you fix output by hand, file after file. They work when you build a process that produces correct output and then let Claude run it. The order of work below follows Anthropic's own write-up and docs.

November 17, 2026 8 min read Workflow
Quick answer

Work in this order. 1) Build a judge: tests or a parity check that runs against both the old and the new code. 2) Write a rulebook of translation rules, a dependency map that sets the order, and a list of gaps that need redesign. 3) Run a small trial, throw the output away, and fix the rules. 4) Translate everything in an implement, review, fix loop driven by a queue. 5) Use compiler errors and crashes as the next work items, grouped by cause. 6) Run the judge until behavior matches. When output is wrong, fix the rules and loop, not the individual files.

Why start with a judge?

Anthropic's post on how it runs large-scale code migrations with Claude Code calls a strong judge the prerequisite. Without an objective check, every file needs human review and the migration stalls. A judge can be the existing test suite, a parity harness that feeds the same inputs to the old and new code and compares the outputs, or both.

Two checks on the judge itself:

No test suite? The post suggests having Claude build one first, using the original code as the source of truth.

Step 2: rulebook, dependency map and gap list

Step 3: trial, discard, refine

Translate a small, representative slice. Read the result critically, then throw it away. The output is not the deliverable; the corrections to the rulebook are. Repeat until a fresh trial comes out right without hand edits. The post recommends putting most human effort here, before the large run.

Step 4: translate in a loop

Run an implement, review, fix loop over a queue of files still to do. Practical points from the post:

In Claude Code, the pieces map to features you already have. Parallel work can run in cloud sessions or local worktrees with claude --worktree. Reviewers fit well as subagents with read-only tools. Scripted loops can call claude -p.

Step 5: compile, run, fix by root cause

Once everything is translated, compiler errors and smoke-test crashes become the work queue. Group them by root cause before fixing. Fifty errors from one wrong rule are one fix in the rulebook and one more loop, not fifty manual edits. Watch for patterns rather than chasing single failures.

Step 6: match behavior

Run the judge against both versions and fix until behavior matches. Only then switch traffic or delete the old code.

How should I set up the repository for this?

The large codebase docs list settings that keep Claude focused:

NeedSetting
Conventions per area, not one giant fileA root CLAUDE.md plus one per package or subsystem
Skip packages you never touchclaudeMdExcludes
Keep Claude out of build output and vendored codeRead deny rules in permissions.deny
Find definitions without reading many filesA code intelligence plugin for your language
Light worktrees in a huge repoworktree.sparsePaths
Touch a sibling package from one session--add-dir or additionalDirectories

For changes that span packages, the docs give two tips. Hand Claude the shared change and its call sites in one session, so the decisions stay consistent. And plan first in plan mode: the plan is written to a file and re-injected after every compaction, so it survives a long session where chat history may not.

What usually goes wrong?

FAQ

Can Claude Code migrate a whole codebase in one prompt?

Not reliably at scale. Large migrations work as a process: judge, rules, trial, loops and verification, with Claude doing the volume work inside it.

What if my project has no tests?

Build the judge first. Have Claude write tests against the original code and confirm they fail when you break that code on purpose.

Should every file be reviewed by a person?

Put human effort into the rulebook, the trial run and the judge. With mechanical verification in place, people review patterns and exceptions rather than every file.

Where do I keep the migration plan?

In a file in the repository. Plan files are re-injected after compaction, and cloud sessions can only see what you have pushed.

Sources

Checked on November 17, 2026 against How Anthropic runs large-scale code migrations with Claude Code (July 16, 2026), Set up Claude Code in a monorepo or large codebase and Common workflows.

See every current command and flag in one reference.

Open the Claude Code Cheatsheet →