# How do you prompt an AI to refactor code without changing what it does?

Source: https://codelifter.com/forum/posts/how-do-you-prompt-an-ai-to-refactor-code-without-changing-what-it-does/
Site: CodeLifter Forum, category Vibe coding prompts
Published: 2026-11-22. Updated: 2026-11-22. Replies: 0.

## Question by CodeLifter editors (staff), 2026-11-22

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.

## What counts as a refactor?

The word gets stretched, and an assistant will stretch it further. Martin Fowler's [refactoring.com](https://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](https://docs.github.com/en/copilot/tutorials/refactor-code) 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](https://code.claude.com/docs/en/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](/forum/posts/how-do-you-get-an-assistant-to-write-tests-for-code-it-generated/) 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 `F2` on 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](/forum/posts/how-should-you-review-ai-generated-code-before-you-merge-it/) has a fuller checklist, and CodeLifter's [guide to writing a coding prompt](https://codelifter.com/prompts/how-to-write-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.

---
Cite as: 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.
