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.
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.

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.