Handing refactors and framework migrations to coding agents
Every codebase carries a list everyone agrees on and nobody staffs: the framework two major versions behind, the dead code nobody dares delete, type coverage stuck at 40 percent, the deprecated internal API that new hires still copy. Using AI agents for refactoring and migration work changes the economics of that list. What used to cost weeks of a good engineer, the person you could least spare, now costs review time and tokens.
In our experience this is the highest-return agent workload most teams have not started. It is also the one where a bit of method separates a clean win from a two-thousand-file pull request nobody will ever merge.
Why this work never got staffed
Deferred maintenance is deferred for rational reasons. It produces no feature to demo. It carries risk with no visible reward, since the best possible outcome is that nothing changes for users. It competes for the senior engineers whose time is already the constraint. And it is miserable: the same transformation applied four hundred times, with attention fading by file two hundred. So it waited, and the carrying cost compounded quietly in every sprint estimate.
What makes refactoring and migration work agent-shaped
Look at the profile of the work. It is mechanical and pattern-based: the same rewrite, recognized and applied across a large surface. It is verifiable: the test suite, the type checker and the build tell you within minutes whether a change holds. And its difficulty runs in opposite directions for humans and machines. Humans start accurate and degrade with boredom; an agent applies the four-hundredth transformation with the same attention as the first.
The judgment in a migration concentrates at the edges: the five percent of call sites that are weird, the module that used the old API in a way the new one does not support. That split suits delegation well. The agent does the volume, the human handles the exceptions, and review effort goes where the risk is. Where a deterministic codemod can do the bulk transformation, use it, and let the agent handle the stragglers the codemod could not parse.
The checkpoint pattern
The failure mode is the heroic run: an agent sent off overnight to "migrate everything", returning with a giant diff that nobody can review or merge. The fix is the discipline you would impose on a contractor.
Slice the work small: one rule, one module, one branch. Require green at every checkpoint (tests, types, build) before the next slice starts. Merge continuously, never in one big-bang branch that drifts from main for three weeks. Have a human sample each slice rather than read every line, with sampling weighted toward the files the agent flagged as unusual. When a checkpoint fails, you discard one slice, not the migration.
Run this way, a framework upgrade becomes a steady background hum: a few slices a day, each one small, reviewable and reversible.
Two prerequisites
Two things must be true before you point agents at structural change. You need a test suite you trust, because refactoring against a weak suite is how behavior changes silently. If the suite is thin, the first agent task is writing the tests themselves, starting with characterization tests that pin current behavior down, which is the standard opening move on legacy systems. You also need fast checks, because nobody follows a checkpoint pattern with a forty-minute build. Half a day spent making the test command fast and documenting it in your context files, part of making a codebase agent-ready, pays back within the first migration.
What to hand over first
Rank by reversibility. Dead code removal first: the diff is deletions, the review is fast, and the effect on team morale is out of proportion to the effort. Then dependency bumps, with changelogs read and breaking changes listed. Then type coverage, file by file. Then lint debt and convention alignment. Framework and language migrations come last, once the team trusts the pattern, because they are where the edge cases live.
This list is also your technical debt register, the same items that get priced against a company in an acquisition. The items have not changed. Clearing them no longer costs a senior engineer’s quarter.
Teams rarely lack the list; they lack the operating pattern: the slicing, the checkpoints, the verification floor that makes delegation safe at this scale. Building that pattern with your engineers, on your own backlog of deferred work, is the kind of thing we do inside an agentic engineering engagement, usually starting with the dead code, because it gives the team its first win within days.