Restructure code you own without breaking it — change only what's worth changing, and prove with tests and a diff that behavior held.
Most refactors start with good intentions and end with a subtle behavior change nobody notices until production. The risk isn't the refactor itself — it's doing it with no way to prove the behavior held. There's also the opposite failure: refactoring everything because you can, instead of the few things that actually hurt. This workflow puts a decision step at the front and a proof step at the end, so you change what matters and can show that nothing else moved.
Each step uses an existing NewPrompt tool, pre-filled by a matching resource. Open the resource to read it, or jump straight into the tool with the inputs ready.
Decide what's actually worth refactoring
Run a review focused on smells and complexity, then ignore most of what it finds. Refactor the parts genuinely costing you — the function everyone fears, the duplication that keeps causing bugs — not every nit.
Lock current behavior with tests
Before changing structure, capture what the code does now in tests. This is the line you refactor against — if these go red, the refactor changed behavior.
Refactor under a no-regression rule
Make the structural change with behavior preservation as the explicit constraint and the tests as the referee. Small, sequenced moves beat one heroic rewrite.
Prove only the structure changed
Diff the relevant output or behavior before and after — same inputs, same results. The diff is your evidence that the refactor was behavior-preserving, not just hopefully so.
The code is cleaner where it mattered, every behavior test is still green, and you hold a before/after diff proving the change was behavior-preserving. The refactor is safe to merge on evidence, not faith.
Use the AI Refactoring Workflow when you already understand and own the code, so it opens with a decision step on what's worth changing. Reach for Legacy Modernization when you don't understand the code — it adds a comprehension step and characterization tests first. Same no-regression care, different starting point.
Tests cover what you thought to test. The diff is a second, cheap check on the actual output for the same inputs — it catches behavior the tests missed. Belt and suspenders for a behavior-preserving change.
A short prioritized refactor list, green behavior tests, the restructured code, and a before/after diff proving behavior held. That diff plus the still-green tests is the deliverable that lets you merge on evidence rather than faith — not a wholesale rewrite, but a defensible, behavior-preserving change.
Work the four steps in order in your own AI tool. Use the code-review prompt to pick what's worth changing, the test-case prompt to pin behavior, the refactor prompt to restructure under a no-regression rule, then the diff checker to compare before and after. You run each prompt and review the output.
The code you own and understand, a way to run its tests, and a sense of which parts actually hurt. Step 1 sharpens that into a prioritized list; Step 2 needs enough coverage to capture today's behavior. Without runnable tests, the no-regression rule has nothing to referee against.
A red test means the refactor changed behavior — that is the workflow working, not failing. Revert the last small move and redo it narrower; sequenced changes make the culprit obvious. If the test itself was wrong, fix it in Step 2 against the original code before refactoring again.
Complete build journeys that include this workflow as a stage.
The full path to taming an inherited codebase — understand it, document its architecture, pin its behavior with tests, then refactor, modernize, review, speed up, and ship it without breaking what works.
Build a test suite that fails for real reasons, not green decoration — coverage across unit, integration, and edge cases, then a review for the gaps.
Update old, risky code you didn't write — safely — by understanding and pinning its behavior in tests before you change a single line.
Speed up code that works but drags — find the actual hot path instead of guessing, understand why it's slow, optimize it, and prove with tests that you changed the speed and nothing else.
A complete AI-assisted review pass — not one prompt — that ends with ranked findings, tests guarding behavior, and a refactor plan when one is warranted.