How do you prompt an AI to refactor code without changing what it does?
Pin the current behaviour with tests before any change, then ask for one small, named restructuring at a time, with explicit limits: same inputs and outputs, same public names, no new dependencies, no bug fixes. Make the assistant run the tests after each step and show you the output, and commit each green step separately.
Cite
CodeLifter Forum, "How do you prompt an AI to refactor code without changing what it does?", https://codelifter.com/forum/posts/how-do-you-prompt-an-ai-to-refactor-code-without-changing-what-it-does/, accessed 2026-11-22.- CodeLifter editorsStaffStaff, CodeLifter ·
What counts as a refactor?
The word gets stretched, and an assistant will stretch it further. Martin Fowler's refactoring.com defines it narrowly: "a change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior." He adds that refactoring "isn't another word for cleaning up code", and that its heart is "a series of small behavior preserving transformations", with the system "kept fully working after each refactoring."
GitHub's guide to refactoring code with Copilot uses the same idea: "restructuring existing code without changing its behavior." Ask an assistant to "clean this up" or "make it better", though, and it will often also change error messages, swap libraries, tighten validation or fix an edge case it disagrees with. Each of those may be welcome, but none is a refactor, and mixed into one diff they are hard to review.
Why do tests have to come first?
Because "without changing what it does" needs a definition the assistant can check. Anthropic's Claude Code best practices put the problem plainly: "Claude stops when the work looks done. If it has nothing to run that tells it whether the work actually is done, 'looks done' is all it has to go on. In practice that makes you the test suite." The same applies to any assistant.
If the code has no tests, ask for tests that record what it does today, including behaviour that looks wrong. These are often called characterisation tests:
Before changing anything, write tests for parseInvoice() that record its current behaviour, including odd cases: empty input, missing currency, negative totals, and the exact error messages. Do not fix anything. If a result looks like a bug, add a comment "CURRENT BEHAVIOUR" and keep the assertion. Run the tests and show me the output.Commit those tests on their own. They are now the contract the refactor must keep. The thread on tests for generated code covers how to check that tests actually assert something.
What should the refactor prompt say?
Name one change and fence it in. A prompt that works:
Refactor parseInvoice() in src/invoice.js. One change only: extract the currency-normalising block into a function normaliseCurrency(raw). Constraints: - Observable behaviour must not change: same return values, same thrown errors and messages, same side effects. - Do not change exported names or function signatures. - Do not add dependencies or change imports beyond what this needs. - Do not fix bugs. If you see one, list it after the diff instead. When done, run npm test and paste the full output.Each line closes a common drift:
Prompt line What it prevents "One change only", with the change named A rewrite of the whole file "Same thrown errors and messages" Callers and logs that match on message text breaking "Do not change exported names or signatures" Breakage in code the assistant cannot see "Do not add dependencies" A new library for something three lines of code did "Do not fix bugs; list them" A behaviour change hidden inside a refactor "Run the tests and paste the output" "All tests pass" claims with nothing run The Claude Code page makes the last point directly: ask for "evidence: the command it ran and its output", because "'All tests pass' on its own tells you very little."
How big should each step be?
Small. Fowler's reasoning on refactoring.com is that "since each refactoring is small, it's less likely to go wrong." With an assistant that is doubly true, because a small diff is one you can actually read. A good sequence for a long function might be: rename unclear variables; extract one block into a function; extract the next; then simplify a conditional. Run the tests and commit after each one. If a step fails, revert that commit rather than asking the assistant to patch forward through a broken state.
For renames, use the editor's own rename where you can. GitHub's guide notes that in VS Code and Visual Studio, pressing
F2on a symbol lets Copilot suggest names, and the chosen name "is changed throughout the project" by the editor's rename, not by a text replacement the model wrote.How do you review the result?
Read the diff with three questions: did anything outside the named change move, did any string or error message change, and did any test change? A test edited during a refactor is a red flag, because the assistant may have made the tests agree with new behaviour. The review thread has a fuller checklist, and CodeLifter's guide to writing a coding prompt explains the constraint lines in more depth.
Checked on 12 November 2026.
Short version
- A refactor changes structure, not observable behaviour; say so in the prompt.
- Pin current behaviour with tests first, bugs included, and commit them.
- Ask for one named change per prompt, with limits on names, errors, dependencies and bug fixes.
- Require the test command and its output, not a summary.
- Commit each green step; revert a failed one instead of patching forward.
Write something first.
Give people something to work with: at least 30 words on what happened and what you tried.
That is too long. Keep it under 6,000 characters.
Write the question as the title, 15 to 140 characters, no links.
Pick a category.
Add a name (2 to 40 characters, no links).
That email address does not look right.
That was quick. Read the thread, then try again.
The form expired. Reload the page and post again.
Something went wrong with the form. Reload and try again.
Please complete the check and post again.
Limit reached for now. Try again later.
This thread is closed to new replies.
This thread no longer accepts replies.
Something went wrong with the form. Reload and try again.
Post a reply or question first (name and email), then this browser can vote, edit and accept answers.
You cannot vote on your own post.
Only the author (within 30 days) or the forum team can do that.
That email already has an account. Use your sign-in link instead.
New accounts are paused for the moment. Try again later.
That was already posted.