4 Best Claude Prompts for Refactoring Legacy Code (2026)
Refactor scary legacy code without breaking it: understand first, pin behavior with tests, refactor in safe steps, and verify nothing moved.
Run = copies the prompt and opens the tool. Remix = save an editable copy to your workspace (free account).
Archaeology first
🟠 Claude
You are a senior engineer inheriting this legacy code: [PASTE CODE — up to a whole module] Produce an archaeology report: (1) what it actually does, (2) every hidden behavior a caller might depend on (ordering, formats, side effects, error swallowing), (3) the load-bearing weirdness — code that looks wrong but is probably compensating for something, (4) what you still can't determine without running it. Do NOT suggest improvements yet.
Why this works: Claude's long context lets it hold an entire module and catch cross-function dependencies.
Good output: A report that makes you say 'oh THAT'S why that line exists' at least once.
Pin behavior with characterization tests
🟠 Claude
Write characterization tests in [FRAMEWORK] that pin the CURRENT behavior — including the ugly parts. Cover every hidden behavior from your report. These tests assert what the code DOES today, not what it should do. Mark any test where current behavior is probably a bug with a // KNOWN-ODD comment instead of 'fixing' it.
Why this works: Characterization tests are the safety harness — refactoring without them is just rewriting.
Good output: A test suite that passes against the untouched legacy code.
Refactor in reviewable steps
🟠 Claude
Now refactor toward [GOAL — e.g. "extract the pricing logic into a pure module"]. Deliver it as a numbered sequence of SMALL steps where every step (a) keeps all characterization tests green, (b) is independently commit-able, (c) is describable in one sentence. Show the code after each step, not just the final state.
Why this works: Step-wise output means you can stop at any point with working code — the core discipline of safe refactoring.
Good output: 3-7 numbered steps, each a small commit you could review in minutes.
Verify and document the delta
🟠 Claude
Compare the final code to the original: list every behavior that changed (there should be almost none), every KNOWN-ODD we preserved, and write a short migration note for the team: what moved where, what's now safe to do that wasn't, and what to watch in the first week after deploy.
Why this works: An explicit behavior-delta check catches the 'accidentally fixed a bug someone relied on' problem.
Good output: A near-empty changed-behavior list and a paste-ready team note.
Frequently Asked Questions
How much code can I paste into one session?
Claude comfortably holds a large module (thousands of lines). Beyond that, refactor one seam at a time and give it the archaeology report from previous sessions as context.
What if I don't have any tests at all?
That's exactly what step 2 is for — characterization tests need no existing suite. They pin today's behavior so steps 3-4 can't silently change it.
Why not just ask AI to rewrite the whole thing?
Full rewrites discard the load-bearing weirdness step 1 exists to find. The graveyard of failed rewrites is why this pack refactors in steps instead.
Make this workflow yours
Remix this pack into your workspace — edit the prompts, track your runs, and never hunt for them in old chats again.