Refactor across 40 files without breaking production
Pin the behavior first, change the structure second, and never let the two mix in one commit.
- Outcome
- A structural change that provably preserves behavior, landed in reviewable increments.
- Time
- Half a day to two weeks depending on blast radius
This workflow is part of PromptKit Pro
A handful of prompts and workflows stay free for everyone — Pro unlocks the full library, including this one, plus the guided runner.
Large refactors fail for one reason, over and over: somewhere in the middle, someone fixes a bug. It's a small bug, obviously wrong, right there in the code being moved — so they fix it. Now the refactor changes behavior, the diff can't be verified by equivalence, review becomes a line-by-line read of 40 files, and when something breaks in production nobody can tell whether it was the move or the fix.
The discipline here is one rule with a lot of scaffolding around it: structural changes and behavioral changes never share a commit. Everything below exists to make that rule survivable — the characterization tests that let you prove equivalence, the mechanical execution that keeps the diff boring, and the incremental landing that keeps each step revertible.
Agents make this both easier and more dangerous. They can execute a mechanical transform across 40 files faster than you can review it, and they will helpfully improve things along the way unless told not to, repeatedly.
When not to use this
Not for code with no users and no tests — just rewrite it. Not while a feature is being actively built in the same files; you'll spend the whole time resolving conflicts. And if you can't articulate what breaks if you don't do this refactor, don't do it.
Did this work?
No behavior change reached users, every commit was independently revertible, and no commit mixed a structural change with a behavioral one.
Tested on claude-opus-5. Evidence status is draft; it moves to battle-tested only on recorded runs, never by hand.