Code Refactoring Prompt Template

“Make this better” is not a refactoring request — it’s an invitation for the model to change whatever it wants, including things you needed to stay exactly the same. Refactoring is improving structure while preserving behavior, not rewriting. Without an explicit boundary on what must not change, a “clean up this file” prompt can silently alter public behavior, drop an edge case, or swap in a generic pattern that doesn’t fit your codebase’s conventions.

This template names the goal specifically, states what must not change, and requires the output to include the updated calling code — not just an isolated refactored function — plus an explicit flag for anything that couldn’t be confidently preserved.

The core template

Act as a senior [language/framework] engineer refactoring this code.

Language/framework: [e.g., TypeScript, Node.js 22]

Goal: [be specific -- e.g., "extract responsibilities into smaller functions," "remove duplication between these two methods," "reduce this function's cyclomatic complexity" -- not just "make this better"]

Code to refactor: [paste the function or module -- keep scope narrow, ideally one unit of behavior]

Must not change: [public interface / exports, output format, existing behavior for [specific cases] -- name explicitly what has to stay stable]

Existing tests: [paste relevant tests, or note "none exist yet" -- if none exist, also note what test coverage this refactor would need]

Provide: a brief responsibility breakdown of the current code, the refactored code, the calling code updated to match the new structure, and an explicit note on anything that could not be confidently preserved without more context.

Why each slot matters

• A specific goal, not “make this better.” Vague goals produce unpredictable scope — the model has to guess what “better” means and often picks a direction you didn’t want. Naming the specific transformation (extract, deduplicate, simplify branching) keeps the refactor targeted.
• Narrow scope. Refactoring at the function or module level, one unit of behavior at a time, is more reliable than a whole-file or whole-codebase pass — narrower scope limits blast radius if something breaks, and keeps the change small enough to review properly.
• “Must not change.” This is the single highest-leverage slot in the template. Without an explicit boundary, a refactor can silently alter public behavior, drop an edge case, or change output format in a way that breaks something downstream that isn’t visible in the code you pasted.
• Existing tests. Tests are the closest thing to a verifiable behavior contract — pasting them lets the model refactor against a concrete definition of “still works,” not just its own read of the code’s intent. If none exist, flagging that tells the model this refactor carries more risk and should note what coverage it would need.
• Requiring the updated calling code, not just the refactored function. A refactored function in isolation still needs to be wired back into everywhere it’s used — without seeing that update, you have to work out the integration yourself, which defeats much of the point.
• The explicit uncertainty flag. A refactor that looks complete but silently changed something it shouldn’t have is worse than one that flags “I couldn’t confirm this edge case is preserved” — the flag tells you exactly where to focus review.

Three filled-in examples

Example 1 — Extracting responsibilities from a large function

Example 2 — Removing duplication between two methods

Example 3 — Reducing branching complexity

Common mistakes this template helps avoid

• Asking for a vague improvement instead of a specific transformation. “Make this better” produces an unpredictable scope; naming the specific goal keeps the refactor targeted and reviewable.
• Refactoring without stating what must not change. This is the most common way a “cleanup” quietly becomes a behavior change — without an explicit boundary, nothing stops the model from altering something you needed to stay the same.
• Requesting a whole-file or whole-codebase refactor at once. Narrower, single-unit scope is more reliable and dramatically easier to review than a sprawling rewrite — large-scope changes correlate with both slower review and higher regression rates.
• Not asking for the updated calling code. A refactored function that isn’t wired back into its call sites still leaves the integration work for you to do by hand.

Frequently asked questions

What if I don’t have existing tests for the code I’m refactoring?

Say so explicitly in the template rather than leaving the slot blank — this tells the model the refactor carries more risk without a verifiable behavior contract, and prompts it to note what test coverage would reduce that risk. Writing even one or two tests for the current behavior before refactoring, if time allows, gives you something concrete to verify against afterward.

How large a piece of code should I refactor in one pass?

Smaller than feels efficient. A single function or a tightly related pair of methods is a more reliable scope than a whole file, and a whole file is more reliable than multiple files at once. Review time and regression rates both tend to be meaningfully worse on large-scope refactors compared to narrow, single-unit ones.

Is it safe to paste proprietary or sensitive code into this template?

Avoid pasting secrets, tokens, or personal data regardless of how you’re using AI tools. For genuinely sensitive business logic you can’t share directly, describe its behavior in plain language instead of pasting the real implementation — “this function validates a session token and returns an error code on failure” is often enough context without exposing the actual code.

Should I apply a design pattern the model suggests if I didn’t ask for one?

Be cautious about unprompted pattern suggestions specifically — models can recommend patterns that are technically valid but add abstraction layers a simple function doesn’t need. If you want pattern suggestions, ask for them explicitly and add a constraint against over-engineering, so the model weighs added complexity against the actual benefit rather than applying a pattern by default.

How is this different from the code review prompt template?

Different goals entirely. The code review template evaluates code against a scope like security or readability without necessarily changing anything. This one actively restructures code while holding behavior constant — review identifies issues, refactoring fixes structural ones without altering what the code does.

Next steps

Once a refactor is complete, run the Code Review Prompt Template against the result before merging — a fresh review pass catches things the refactoring process itself might not flag. For more ready-to-use templates, browse the Prompt library.