Refactoring with AI

Refactoring is the one kind of change where the user is supposed to notice nothing. You improve the shape of the code, and every output, error, and side effect stays exactly as it was. That is also what makes an AI refactor dangerous. The assistant predicts plausible code, and a refactored file that looks tidier than the original reads as a success even when it quietly changed behaviour.

Picture a developer asking an assistant to clean up a sprawling validateOrder function. The reply is genuinely nicer: shorter, well-named, the nesting flattened. The developer skims it, sees no obvious problem, and merges. What the cleanup silently dropped was one branch, the guard that rejected orders with a negative quantity, because the model folded several conditions into one and lost an edge case along the way. There was no failing test, because nobody had written one for negative quantities. Weeks later a refund flow lets a negative line item through, and the team is debugging a money bug that the refactor introduced and the diff hid behind cleaner formatting.

The research describes this exact shape. Two independent studies in 2024 and 2026 found state-of-the-art models clearing only about 40% of complex refactoring tasks, and the common failures are the quiet ones: dropping a branch that held input validation, inverting a boolean so a condition reads backwards, mishandling JavaScript's this binding when extracting a function. A 2026 SonarSource survey found 88% of developers reporting negative AI effects on technical debt, and 53% pointing to code that looked correct but was unreliable.

The payoff of doing it well is that you keep all of the speed and remove almost all of the risk. The shared spine of this whole topic is that the assistant predicts from its context, and your control comes from three levers: the context you supply, the plan you agree before it writes, and the diff you review before you keep it. A refactor leans hard on all three, with one addition that is specific to this kind of change. Because behaviour must stay fixed, you get a fourth check the model cannot fake: a test suite that was green before and has to be green after. The mechanism that turns that into a reliable safety net is what the next section breaks down.

A safe refactor is a chain of behaviour-preserving transformations. Each step changes the structure and leaves the observable behaviour identical, which means a passing test before a step should still pass after it. Get the pieces in the right order and the model can move fast without you losing control. The pieces are these.

• The safety net. A green test suite that exercises the behaviour you are about to reshape. It is what tells you a step preserved behaviour or broke it. No net, no safe refactor.
• Characterization tests. When the code has no tests, you write tests that record what it actually does today, including its quirks, before you change anything. They pin current behaviour so the refactor has something to stay faithful to.
• The constraint. An explicit statement of what must not change: the signatures, the return shapes, the thrown error types, the side effects, the public interface. This is the rule the model is forbidden to break.
• The small move. One rename, one extraction, one inlined variable at a time, each followed by a full test run. Small moves keep every step inside what your review and the model can actually check.
• The diff. The exact lines that changed, read against the constraint, not against the prose summary the model wrote about itself.

The distinction that decides success is Martin Fowler's two hats. When you wear the refactoring hat, every change is behaviour-preserving and the tests stay green throughout; a red test means you made a mistake, not that the test is wrong. When you wear the adding-function hat, you are changing behaviour, so you write new tests and existing ones may legitimately change. The two hats never share a commit. Mixing them is how a behaviour change hides inside the noise of a hundred moved lines, where no reviewer will find it.

The second decisive fact is where models break. They do reasonably well on a localized, single-file edit. They collapse on repository-level reasoning: tracking every call site of a renamed function across files, updating a signature consistently everywhere it is used, rewiring all the callers. Most AI refactoring failures are incomplete compound transformations, the extraction that happened but left three callers pointing at the old shape. The practical consequence is that you ask the assistant to map the blast radius first, so you can see whether the move is a single-file edit it can handle or a cross-file change where you need to verify every call site yourself. With the order in place, the next section walks one refactor through end to end.

Maya, a developer, inherits a checkout module with a parseTotals function in cart.ts. It is two hundred lines, deeply nested, and has no tests. She wants to extract the validation logic into a clean validateOrder(order) so it can be reused, and she wants behaviour to stay byte-for-byte identical. Here is how she runs it.

1. Build the safety net first. Because the code is untested, she does not refactor yet. She asks the assistant to write characterization tests that pin the current behaviour, including the awkward cases: empty cart, negative quantity, missing field. The prompt is explicit, "do not change the code, capture what it does today, and run the tests so I can see them pass." Two of the captured behaviours look like bugs, but she keeps them for now; the refactor's only job is to preserve behaviour, and fixing bugs is the other hat.
2. State the constraint up front. She writes it at the top of the refactor prompt: keep the function signature, return the same shape, throw the same RangeError on bad totals, preserve the empty-cart and negative-quantity behaviour the characterization tests just locked. Do not edit the tests.
3. Ask for the blast radius. Before any edit, she asks the assistant to list every file and call site the extraction touches. It names cart.ts and three callers in checkout.ts and refund.ts. Now she knows this is a cross-file move, not a single-file edit, so the call sites need checking.
4. One move, then run. She has it perform the extraction only, no other cleanup, and produce one diff. She runs the full suite. Nineteen of nineteen characterization tests stay green. One caller in refund.ts still references the old inline shape, exactly the incomplete-compound-refactoring failure mode. She has the assistant fix that one caller and runs the suite again.
5. Read the diff against the constraint. The diff is forty lines. She checks the extracted validateOrder against the original line by line: same conditions, same error type, no dropped branch. The negative-quantity guard is intact. She rejects nothing.
6. Commit the refactor alone. She commits the extraction as one behaviour-preserving change, with a message that says so. The two suspected bugs she found earlier go on a separate ticket, to be fixed under the adding-function hat in their own commit.

The before and after is the lesson. Without the characterization tests, the dropped guard from the first section would have shipped invisibly. With them, the refactor was provably faithful, the one stale caller was caught in minutes, and the structure improvement landed clean. Maya and this same validateOrder change carry into the pitfalls below.

Each trap here feels like progress while quietly turning the refactor into a behaviour change you cannot see.

• Refactoring with no net. Reshaping untested code feels efficient because nothing turns red. Nothing turns red because nothing is watching. The fix is to write characterization tests first, capturing current behaviour before the first move, so a shifted behaviour has something to fail against.
• Editing the test to make it pass. When a test fails mid-refactor, the tempting shortcut is to adjust the test. That converts your safety net into a rubber stamp. While wearing the refactoring hat, a red test means the move broke something; revert the move, do not soften the check.
• Accepting the clean-looking rewrite. A large diff that reads tidier than the original earns trust it has not proven. Tidier formatting hides dropped branches and inverted conditions. The fix is to keep moves small enough to read fully, and to review against the constraint and the tests rather than against how clean it looks.
• Mixing the two hats. Slipping a small behaviour fix into a big structural commit feels harmless and saves a commit. It also buries the one line that matters under a hundred that do not. Keep the hats in separate commits so the real change is visible.

Then the genuine edge cases. The cross-file rename the model leaves half-done. Repository-wide changes are where models fail most, by updating the definition and missing some callers. The handling is to refuse to treat a cross-file refactor as one step: have the assistant enumerate every call site first, apply the change, then verify with a compile or a full test run that no caller still references the old shape, exactly as Maya caught the stale refund.ts caller.

The behaviour that turns out to be a bug. Characterization tests pin what the code does, including its mistakes. If your refactor would "fix" one of those mistakes, that is a behaviour change wearing a refactor's clothes. The 2026 wrinkle is that an assistant will often quietly correct an obvious-looking bug while restructuring, which breaks behaviour preservation and any caller that depended on the old quirk. Keep the suspected bug behaviour green through the refactor, and fix it deliberately afterward under the adding-function hat, with its own test and its own commit. Keeping that discipline consistent when several people refactor the same repo is where scale comes in.

One developer can hold the two-hats rule in their head. The moment a second person, a second tool, or a second month is involved, the discipline has to live in shared artifacts, or the history fills with commits that quietly mixed structure and behaviour and nobody can bisect.

The first durable artifact is the test suite itself, treated as the contract. A team that refactors with AI keeps behaviour-preservation tests in version control and runs them in CI, so a refactor that breaks behaviour fails the pipeline rather than relying on a tired reviewer to spot it. Governed refactoring, validated by tests and CI, is what separates a safe AI refactor from a suggestion that merely looked right in an editor. Organizations with systematic testing protocols for refactored code report far fewer post-deployment issues.

The second artifact is the small pull request. Review capacity, not code volume, is the bottleneck in 2026, and an assistant can produce a thousand-line refactor in seconds that no human can deeply review. The widely cited bar is to treat 200 lines as the target and 400 lines as a hard ceiling, since reviews of larger diffs turn superficial and PRs over 400 lines often stall for days. Smaller, single-purpose refactor PRs cut cycle time by 30–40% and let a reviewer actually check the diff against the behaviour constraint. A lead, Priya, sets a PR size gate in CI and adds two lines to the PR template: which assistant produced the change, and the prompt or task that drove it, so a reviewer can ask the right question.

The third is a shared statement of the rule, in a versioned file the tools read, such as CLAUDE.md or AGENTS.md. A short entry, "refactors must be behaviour-preserving, keep tests green, never edit a test to pass during a refactor, list call sites before a cross-file change," travels with the repo and reaches every contributor's assistant. The tools support the small-step rhythm directly: Cursor's Plan Mode, toggled with Shift+Tab, writes a reviewable Markdown plan into .cursor/plans that you edit before the agent touches code, and Claude Code's plan mode (also Shift+Tab, or claude --permission-mode plan) reads the codebase without writing, so you agree the sequence of moves before any diff exists.

The durable principle to keep, whatever the size of the team: a refactor is only safe when behaviour is locked before you start and provably unchanged after you finish, and when each move is small enough that a human can read the diff. Start with one small thing. The next time you reach for a refactor on untested code, write the characterization tests first and refactor nothing until they are green.