The Best Prompt for Refactoring Code

Why this prompt works

How to use it

1. Paste one coherent unit: a function, a class or a small module. Several hundred lines at once makes the inventory shallow.
2. Choose a single goal. If you want both shorter functions and less duplication, run the prompt twice and commit in between.
3. List what must not change in concrete terms: signatures, return shapes, error types, database writes, output order.
4. Read the behavior inventory and correct it before trusting anything that follows. A wrong inventory means an unsafe refactor.
5. Apply the steps one at a time and run your tests after each, starting with the characterization tests if the prompt wrote any.
6. Review every row marked no or uncertain in the equivalence table, and open separate tickets for the suspected bugs.

AI model compatibility

“Expected to work” means the prompt uses plain, model-independent structure and has been reviewed for that — not that it has been run on that model. A model is marked Tested only when a test record is published below.

Worked example

Scenario: A developer has inherited a 90-line order-processing function and needs to add a new discount type without breaking existing ones.

I want this code refactored without changing what it does. You are acting as a careful senior engineer: structure may change, observable behavior may not.

<code language="JavaScript (Node.js)">
A single processOrder(order, user) function that validates the order, applies three kinds of discount in nested if/else blocks, calculates tax, writes to the database and sends a confirmation email
</code>

Refactoring goal: Break up a long function or class
Must stay exactly as it is: The processOrder signature and the object it returns, the order of the database write and the email, and the error messages thrown for invalid orders
Test coverage today: Partly covered
Project conventions to follow: Async/await, no classes, Prettier defaults

Work through four phases and show each one.

PHASE 1 - BEHAVIOR INVENTORY
List everything a caller or the outside world can observe about this code: inputs accepted, return values, mutations of arguments or shared state, I/O and its order, exceptions and when they are raised, and behavior on empty, null or malformed input. Include behavior that looks accidental or wrong. This list is the contract for the rest of the task.

PHASE 2 - PLAN
Name the specific problems that stand in the way of the goal, with line references. Then give an ordered list of refactoring steps. Each step must be one recognizable move (extract function, rename, inline variable, replace conditional with guard clause, introduce parameter object, and so on) and small enough to commit and test alone. If test coverage is partial or missing, make step 0 a short set of characterization tests that pin current behavior, and write them.

PHASE 3 - REFACTORED CODE
Apply the plan and show the complete result. Keep public names, signatures, argument order, return shapes and error types unchanged unless I listed them as open to change. Do not add features, new dependencies, logging or extra validation. Do not reformat lines you have no other reason to touch.

PHASE 4 - EQUIVALENCE CHECK
Go through the Phase 1 inventory item by item in a table: behavior, preserved (yes / no / uncertain), reason. Anything marked no or uncertain must be explained.

Rules
- If you see a likely bug, leave its behavior intact and report it under "Suspected bugs (not fixed)".
- If the goal cannot be reached without a behavior change, stop after Phase 2 and tell me which behavior would change.
- If the code depends on something not shown, state what you assumed about it.
- Prefer the smallest refactor that reaches the goal. A rewrite is not a refactor.

End with: a one-paragraph summary of what is better now, the list of suspected bugs, and the tests you would run before merging.

What a good response should contain

• An inventory that notes non-obvious behavior, such as which discount wins when two apply and that the email is sent only after the write succeeds
• A step 0 containing characterization tests for the discount paths that lack coverage
• A plan of small moves, for example extracting validateOrder, calculateDiscount and calculateTax, with database and email calls left in processOrder
• Refactored code with the same exported signature and thrown messages, and no new dependencies
• An equivalence table with at least one honest "uncertain", such as rounding order in the tax calculation, and a separate list of suspected bugs

This is an illustrative scenario showing how to fill in the prompt and what to look for. It is not a recorded model output. Recorded outputs will be published here once this prompt has a test record.

Testing and editorial review

No test record has been published for this prompt yet. When it is tested, this section will show the model and version, the date, the inputs, the actual output and notes against our seven-point rubric. We do not publish numerical scores.

Limitations and things to check

• The equivalence check is reasoning about code, not running it. Only your tests, or characterization tests you run before and after, can establish that behavior is unchanged.
• Behavior that depends on code outside what you pasted, such as global state, decorators, middleware or monkey-patching, is invisible to the model.
• Performance characteristics can shift after a refactor even when outputs are identical. Measure if the code is on a hot path.
• Taste varies. The result reflects common conventions for the language unless you state your team's own.
• Very large files exceed what a single reply can restructure well. Work one unit at a time.

Alternative prompts

Related resources

All Coding prompts →

Frequently asked questions

Sources and references

1. How to do a code review — Google Engineering Practices
2. Prompt engineering overview — Anthropic

Was this prompt useful?