How to Prompt AI for Refactoring

Why refactoring needs careful prompting

AI assistants are good at mechanical restructuring and bad at knowing which behavior is intentional. Asked to “clean up” a module, a model will happily fix “bugs” your customers rely on, change error messages other systems parse, or reorder operations with side effects. The fix is to make “don’t change behavior” concrete and checkable.

Step 1: Pin down current behavior with tests

Before any refactoring, make sure tests describe what the code does today, including its odd parts. If coverage is thin, start with this prompt:

Read src/billing/invoice.ts. Don't change it.
Write characterization tests that capture its current behavior,
including edge cases: zero amounts, negative amounts, missing tax
rates, rounding. If a behavior looks like a bug, still test the
current behavior and add a comment "CURRENT BEHAVIOR, possibly a bug".

Run the new tests against the unchanged code. They must all pass before you continue.

Step 2: Ask for a plan, not code

Have the assistant propose the steps and wait for your approval. Planning first catches bad ideas while they are cheap to reject.

I want to refactor src/billing/invoice.ts so tax calculation is a
separate, pure function that can be tested on its own.

Constraints:
- No behavior changes. The characterization tests must keep passing
  unchanged.
- Don't change the public exports of invoice.ts.
- No new dependencies.

Propose a plan as a numbered list of small steps, each one leaving
the tests passing. Don't write code yet.

Reject steps that mix restructuring with behavior changes, and steps too large to review in one go.

Step 3: One step at a time

Approve and run one step, verify it, commit it, then continue.

Do step 1 only. Then run the tests and show me the result.

Small steps keep each diff readable, and a commit per step gives you an easy way back if a later step goes wrong.

Step 4: State what must not change

Name the things that are easy to break by accident. Good constraints to include:

• public function names, signatures and exports
• error types and error message text
• log messages and metrics names other systems depend on
• the order of side effects, such as database writes and emails
• performance-sensitive paths (“don’t add database queries inside loops”)

Step 5: Verify every step

After each step, check the diff and the test results yourself. Watch for edited test files: in a pure refactoring, existing tests should not need to change. If the assistant changed a test to make it pass, stop and ask why.

Prompt patterns for common refactorings

When not to use AI for a refactoring

Do it by hand, or in much smaller steps, when the code has no tests and can’t easily get them, when behavior depends on timing or concurrency, or when you can’t verify the result. An AI that produces a large, untested refactoring quickly hasn’t saved you time; it has moved the work into review and production.