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:
- Prove it fails. Break the code on purpose and confirm the judge catches it. The post's line is that a judge that does not catch breakage is not a judge.
- Guard the tests. If tests are rewritten too, check adversarially that no assertion was weakened along the way.
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
- Rulebook. How each construct in the old code maps to the new one: naming, error handling, logging, async patterns, library replacements. Keep it in the repository so every session and subagent reads the same rules.
- Dependency map. Which files depend on which. It decides the order and shows cycles early; cyclic imports can cause large waves of errors later.
- Gap list. Places where the new language or framework needs a redesign rather than a translation, such as manual memory management or implicit interfaces.
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:
- Parallelize independent units. Files that do not depend on each other can be processed at the same time.
- Make it resumable. Rebuild each batch from what is on disk, so an interrupted run picks up where it stopped.
- Match the model to the job. Smaller models for high-volume translation, larger ones for review and rule-writing. The post's advice is not to use the largest model for everything.
- Make review adversarial and verification mechanical. A reviewer that tries to find problems, and checks that do not depend on anyone's judgment.
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:
| Need | Setting |
|---|---|
| Conventions per area, not one giant file | A root CLAUDE.md plus one per package or subsystem |
| Skip packages you never touch | claudeMdExcludes |
| Keep Claude out of build output and vendored code | Read deny rules in permissions.deny |
| Find definitions without reading many files | A code intelligence plugin for your language |
| Light worktrees in a huge repo | worktree.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?
- Hand-patching output. The fix disappears on the next loop. Fix the rule.
- Agents that are too cautious. The post notes blunt instructions can help when Claude hedges instead of making the change.
- Unplanned token spend. Cost concentrates in loops, so design them deliberately and cap them.
- Huge sessions. Long sessions compact. Keep the rulebook and plan in files, not in chat.
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.