The Best AI Prompts for Refactoring Legacy Code
Legacy code doesn't come with a manual. You inherit a function that's 300 lines long, has no tests, and the original author is long gone. You know it needs to change, but touching it feels like defusing a bomb blindfolded. AI tools won't rewrite your entire codebase for you — but with the right prompts, they dramatically shrink the time between "I don't understand this" and "I can safely change this." Here are the prompts I reach for, in the order I actually use them.
1. Start with a plain-English explanation of what the code does
Before you touch anything, you need to understand it. Paste the function or module and ask:
Explain what this code does in plain English. Describe:
1. Its purpose (what business problem it solves)
2. Its inputs and outputs
3. Any side effects or external dependencies
4. Edge cases it appears to handle
5. Anything that looks unusual or potentially buggy
Here is the code:
[paste code]
This gives you a mental model fast. Don't skip it — even if you think you understand the code, the AI often surfaces a side effect or edge case you glossed over.
2. Identify the smell before you prescribe the fix
Jumping straight to "refactor this" produces mediocre results. Instead, ask for a diagnosis first:
Review the following legacy code and list every code smell you can identify.
For each smell: name it, quote the specific lines involved, and explain why it's a problem.
Do not suggest fixes yet — just audit.
[paste code]
Getting a structured smell list forces the AI to slow down and reason about the code rather than produce a cosmetically cleaner version of the same mess.
3. Ask for a refactoring plan, not just refactored code
Once you have the smell list, ask for a sequenced plan before asking for any new code:
Given the code smells you identified, produce a step-by-step refactoring plan.
Order the steps from lowest risk to highest risk.
For each step, explain: what changes, why it's safe to do in isolation, and what could break.
Do not write code yet.
This is the prompt that saves the most time. A plan exposes assumptions you can challenge before you've committed a line of code. It also gives you natural stopping points if you're time-boxed.
4. Generate a characterization test suite before refactoring
Legacy code without tests is a minefield. Use the AI to generate "characterization tests" — tests that document current behavior, not ideal behavior:
Write a suite of unit tests for the following function that captures its current behavior exactly — including any behavior that looks wrong.
The goal is not to test correctness; the goal is to detect if refactoring changes the output.
Use [your test framework, e.g. Jest / pytest / RSpec].
[paste code]
Run these tests, commit them, and now you have a safety net. Any refactoring that breaks a test is a regression you need to understand before merging.
5. Refactor one smell at a time, not all at once
Now you're ready to change code. Do it incrementally:
Refactor ONLY the following problem from the code below: [name one smell from your list, e.g. "extract the nested conditional into a separate function"].
Do not change any other logic.
Show me the before and after side by side and explain every change you made.
[paste code]
This pattern is one of the ones I've packaged into The AI Leverage Playbook: 50 Prompts & Workflows for Engineers — but the version above is enough to get value on its own.
Scoping the prompt tightly is the key move. When you ask AI to "refactor everything," it over-reaches and introduces changes you didn't ask for, review, or understand. One smell per prompt keeps the diff reviewable.
6. Ask for a risk assessment on your final diff
Before you open the PR, paste your final diff and ask:
Review this diff. Identify any changes that:
- Could introduce a regression
- Change behavior in a way that isn't obvious from the variable/function names
- Should be covered by a test that doesn't exist yet
Be specific. Quote the lines you're concerned about.
Treat this like a second pair of eyes on your PR — one that reads every line without getting bored.
The sequence matters as much as the prompts
These six prompts are most effective in order: understand → audit → plan → safety-net → change → validate. Skipping steps (especially the characterization tests) is how you end up with a "refactored" codebase that breaks in production on an edge case nobody thought to test.
None of these prompts require a specific AI tool — they work with whatever assistant you're already using. The discipline is in the sequence, not the syntax.
I break down one workflow like this every week in The AI Leverage Weekly — practical, no fluff, free. Subscribe: https://theaileverageweekly.beehiiv.com/subscribe?utm_source=devto&utm_medium=article&utm_campaign=long_w8
Top comments (0)