How to migrate a large codebase with AI coding agents

The ticket has been open for a year. "Upgrade to v3." Everyone agrees it should happen. Nobody has started, because starting means editing four hundred files by hand and living in a half-broken branch for a fortnight.

That's most migrations: a framework major, an ORM swap, moving off a deprecated API, JavaScript to TypeScript. The work isn't hard. It's enormous, repetitive, and unforgiving if you stop halfway.

Which makes it close to the ideal job for an AI coding agent, as long as you don't hand it over in one sentence.

(The steady drip of ordinary version bumps is a different job, with its own triage: that's dependency upgrades. This post is about the big one.)

"Migrate the codebase to v3" is not a task

Try that prompt and you'll get something that looks like progress: forty files changed, a confident summary, and a test suite that no longer runs. Somewhere in there the agent hit a call site that didn't fit the pattern, invented a workaround, and carried on without mentioning it.

Migrations punish that. A half-applied change isn't 50% done: it's a codebase where two conventions are live at once, and every change after it has to know which world it's in.

So stop treating a migration as one task. Treat it as an inventory, a recipe and a queue.

Start with a read-only pass

Your first agent session shouldn't edit anything. Ask for a survey:

Find every use of the old API in this repo. Group the call sites by usage pattern, count each group, list the files, and flag anything that doesn't fit a group. Don't change any code.

What comes back is the real scope, and it's usually a surprise: three hundred call sites in two shapes you can automate, eleven that are genuinely different, and a directory nobody remembered was still on the old thing.

That list is your plan, the same move that makes agents good at learning an unfamiliar codebase: ask for a written artefact first, and check it before a single file changes.

Migrate one file, then write the recipe

Pick the most representative file in the biggest group and do it properly, yourself, or with the agent while you watch. Then write down what happened:

• the exact before/after shape, with a real example from your repo
• what to do about imports, types and the file's tests
• what to leave alone
• what to do when a file doesn't match: stop and flag it, never improvise

That's your migration spec, the difference between an agent copying a known-good transformation and one redesigning your code file by file. It's spec-driven development, applied three hundred times.

Separate the mechanical from the judgment calls

Every migration splits roughly 80/20. The mechanical majority is a pattern with clear edges: agents do it quickly, accurately and boringly. The rest needs decisions: the module with the custom caching layer, the place someone relied on a quirk of the old behaviour.

Sort them before you start, because an agent won't tell you it was unsure. It produces something plausible instead. Do the judgment files attended, one at a time.

Keep main shippable the whole way

Don't run a migration as one branch that lives for two weeks. Batch it by module and treat each batch as an ordinary change: branch, migrate, tests green, review, merge.

Twelve reviewable diffs beat one four-hundred-file diff you'll skim and approve out of exhaustion. And when the migration gets interrupted (it will), you stop at a clean boundary, not in a tree where half the app speaks v2 and half v3. If both versions must coexist, put the compatibility shim in the recipe up front.

Give it a finish line a machine can check

"Does it look migrated?" is not a completion criterion. These are:

• the test suite passes, unmodified wherever possible
• the type checker or compiler is clean
• searching the repo for the old API returns nothing outside the shim

That last one deserves to be its own acceptance criterion: agents are good at making their work look finished, and a search returning zero results is a fact. It's why writing the test first works so well with agents: objective feedback doesn't need you paying attention.

Then run the batches in parallel

This is where a two-week migration becomes an afternoon. Once you have a recipe and independent batches, nothing says you do them one at a time. Four agents on four modules is four times the throughput, provided they aren't fighting over one working tree, which is what git worktrees exist to fix.

Your bottleneck moves to review. That's the right bottleneck to have.

Where SanuDesk fits

This is the workflow SanuDesk is built around. It's a desktop app that tiles your Claude Code, Codex and Gemini sessions into one grid, with a Kanban board the agents take their work from.

The inventory becomes the board: one card per batch, the recipe in the notes, the finish line in the acceptance criteria. Deploying a card opens a fresh session briefed with exactly that, and four batches move side by side instead of hiding in terminal tabs. When a session finishes, its card lands in review with a what-changed note.

Loops cover the part everyone forgets: after the migration ships, a scheduled run that searches for the old API and flags anything creeping back in. SanuDesk drives the agent subscriptions you already pay for (bring your own models), and the free tier is a real one.

Pick the migration you've been avoiding

You don't need a migration sprint. Take the upgrade rotting in your backlog, spend one session on the inventory and one file on the recipe, and put the first batch on the board tonight.

It was never difficulty that stopped you. It was volume, and volume is the one thing you no longer have to pay for by hand.

Download SanuDesk free and point a workspace at the repo, or see how the grid, the board and Loops fit together on the features page.