concord ai

Run large code migrations with AI agents step by step

Learn how to run a safe, reviewable migration with AI agents by starting small, writing the pattern, and scaling in batches you can actually review.

Alex Choi, AI Engineer5 min read

the short answer

Migrate one module by hand with the agent, write the pattern, then fan out in batches small enough to review before each step.

Abstract technical illustration for the article Run large code migrations with AI agents step by step

By the end of a large code migration you want a merged pull request whose diff you actually reviewed, tests that pass, and a plan you can repeat without surprises. To get there, start with one representative module, write the pattern that worked, then fan out in batches small enough that a reviewer can read every line before you merge.

Pick the smallest module that still teaches you something

Choose a module that is small enough to finish in hours, not days, but large enough to surface the real problems you will meet at scale. If the module has configuration, tests, and at least two call sites, you will learn how the agent handles imports, runtime guards, and test updates. If it is a leaf module with no dependents, you will not learn how a migration ripples through the system.

Run the agent on that module with a prompt that names the destination pattern, the files to change, and the tests to keep passing. Keep the prompt short so you can reuse it later. If the agent drifts, stop it, adjust the prompt, and try again. You are not optimizing for speed yet; you are writing the pattern that will scale.

Record the working pattern in code and prose

After the agent finishes the module, copy its changes into a branch and commit them. Then write a short design note that lists the files changed, the prompt you used, the tests that passed, and the assumptions you made. That note becomes your migration runbook. Without it, the next batch starts from scratch and the same mistakes repeat.

Keep old and new code working side by side

Use feature flags, runtime guards, or interface switches to run both the old and new implementations at the same time. That lets you compare behavior in production and roll back if the new code breaks something unexpected. If you cannot do that, you must test the new code in a staging environment that mirrors production traffic, which slows you down.

Write a mechanical diff check the agent can run

The agent should diff file counts, line counts, and test pass rates between the old and new versions. It should also run a curated set of regression tests you trust to catch regressions. If any of those checks fail, the agent stops and you review the failure before proceeding. Those checks are the safety net that lets you scale.

Fan out in batches you can actually review

Split the remaining modules into batches whose diffs fit on one screen and whose review you can finish in an hour. If a batch grows beyond that, split it further. Each batch becomes a pull request that you review, merge, and deploy independently. That keeps the migration incremental and reviewable instead of a single giant change that nobody can read.

Let the agent propose the batch, but let a person decide to merge

The agent can group modules by dependency and propose a batch, but the human decides when the batch is ready to merge. The human checks the prompt, the design note, the diff, and the mechanical checks. When everything aligns, the human merges and deploys. That split of labor keeps the agent productive while keeping the system safe.

Stop and fix when mechanical checks fail

If the mechanical diff or regression tests fail, the agent stops and you investigate. If the failure is a false positive, adjust the check. If it is a real regression, fix the code or revert the batch. Do not override the check to keep the migration moving. The moment you override a check you lose the evidence that the migration is still safe.

After each batch merges, update the runbook with the new files changed, the tests that passed, and any new assumptions. That keeps the runbook accurate as the migration progresses. When the runbook covers the entire codebase, you can hand the migration to a less experienced engineer or even automate it fully, because you have the pattern that works.

What to do when the agent can’t resolve a conflict

Some conflicts require human judgment: ambiguous interfaces, missing tests, or changes that affect multiple teams. When the agent can’t resolve a conflict, it should stop and surface the conflict in a shared workspace so the right people can see it. Overlap warnings arrive when an agent claims work, which the shared workspace records for every agent.

The human then proposes a resolution, commits it, and lets the agent continue. That keeps the agent productive while ensuring the resolution aligns with the system’s design. Without a shared workspace, those conflicts get buried in pull request comments and are easy to miss.

How to know when to pause the migration

Pause the migration when the mechanical checks start failing repeatedly, when the agent drifts from the stated pattern, or when the runbook no longer matches reality. Those signals tell you the pattern is not yet repeatable. Pushing forward without fixing the pattern leads to regressions that are expensive to roll back. The pause is not a failure; it is the moment you gain the context needed to scale safely.

After you fix the root cause, resume the migration with a new batch. Each pause and resume cycle improves the runbook and the agent’s prompts, so the next batch is safer than the last. Eventually the migration finishes with a set of verified changes and a reusable pattern you can apply to the next migration.

large code migrations with ai agentsai agent migration guidemigrate codebase with aiai for code refactoringscaling ai code changes

Common questions

Why migrate one module by hand with an AI agent before automating the rest
A single module lets you write and test the pattern once, so you know what to expect when you scale. Mistakes compound at scale, and a small run gives you the evidence to decide whether to continue.
How do you keep old and new code working side by side during a migration
Use feature flags or runtime guards to switch between implementations. That way, you can compare behavior while the migration is in progress and roll back if something breaks.
What kind of mechanical checks can an agent run to verify a migration
The agent can diff file counts, line counts, and test pass rates, and run a curated set of regression tests. Those checks surface regressions before you open a pull request.
When should a person intervene during an AI-driven migration
Intervene when the agent proposes changes outside its stated scope, when it can’t resolve conflicts, or when the mechanical checks fail repeatedly. That’s when human context prevents drift.
How do you decide when a batch is small enough to review
A batch is small enough when a human reviewer can read every changed file and the diff fits comfortably on one screen. Beyond that, the review itself becomes a bottleneck.

written by

Alex Choi, AI Engineer

Builds tooling for teams whose code is mostly written by coding agents.

Give your agents one shared work-state.