Prompt Engineering

Refactor Prompt — the Behavior Preservation Contract

"Refactor this code" invites silent behavior changes. The refactoring contract preserves business rules, outputs, and side effects — and flags uncertainty instead of deciding it.

Open in Refactor Prompt Builder

Overview

Most refactor prompts hand the model code and an adjective. The refactoring contract structures the transformation instead: a goal with named priorities, a risk profile that sizes the change set, seven safety rules that apply at every risk level, and the flagship — behavior preservation requirements covering observable behavior, business rules, outputs, side effects, and integrations. Uncertain behavior becomes a question, never a silent decision. This setup loads a classic large-method decomposition on business-critical code to show the full contract.

How to use this resource

Name the goal, not just the wish

Readability, maintainability, simplification — each goal carries different priorities and different known failure modes.
Size the risk

Conservative demands the smallest change set; Aggressive allows restructuring — but behavior preservation never turns off.
Read the assumptions first

Every transformation that depends on an UNVERIFIED assumption arrives flagged — that list is where regressions hide.

Why This Works

Naming what must be preserved beats hoping the model preserves it
The risk profile separates ambition from safety — they are different axes
Flagged uncertainty turns silent behavior changes into reviewable questions

Best for

Developers using chat AIs to restructure real code
Code where a hidden behavior change is expensive
Teams standardizing how AI-assisted refactors are requested

Not for

Finding what is wrong with the code — that's the Code Review Prompt Generator
Fixing a failure or error — diagnose it first with the Debugging Prompt Generator

Use cases

Decomposing a giant method without altering a business rule
Getting a change list with reasons instead of a silent rewrite
Forcing the model to skip what it cannot verify

FAQ

Does the refactor prompt change or merge my code automatically?

No — the prompt returns refactored code plus a change list and a validation plan, but it never applies, runs, tests, or merges anything. You paste the output into your own AI tool, then review and merge yourself. Under the seven safety rules, uncertain behavior arrives as a flagged question, and the conflict rule 'behavior wins' stops it from silently compromising your business rules.

What context should I give before asking AI to refactor code?

Paste the code into the 'Code to refactor' block, then fill the EXISTING CODE CONTEXT: whether it's business-critical, the language (or 'infer it'), and stated constraints like 'order state transitions must happen in exactly the current sequence.' Also set the refactoring goal and a RISK PROFILE level — Conservative, Balanced, or Aggressive. That context lets the model size the change set and know what must survive untouched.

How do I check a refactor suggestion is safe before merging it?

Run the VALIDATION STRATEGY the prompt returns: a before/after verification plan naming specific inputs and the outputs that must match, a behavior comparison per changed unit, the existing regression tests that must pass, and integration verification for every external touchpoint. Then read the ASSUMPTIONS list — anything marked UNVERIFIED, or flagged as possibly behavior-affecting, is where a regression can hide and needs your own review before merge.

What does the refactor prompt actually return?

It returns the complete refactored code — no elided sections or 'rest unchanged' placeholders — then a change list stating, for each change, what changed, why it serves the goal, and the behavior impact (expected: none). Any change that could plausibly alter behavior comes flagged with the check that confirms it doesn't, and safe transformations skipped for caution appear under 'Suggested but not applied' with what would unlock them.

Customize This Resource

Opens this setup in Refactor Prompt Builder. Generate to get the full refactoring contract — then adjust the goal, risk level, and validation strategy.

Open in Refactor Prompt Builder

Prompt Template

Copy it as-is, or use Open in Refactor Prompt Builder to load it pre-filled and customize it with your own context.

REFACTORING OBJECTIVE
Decompose the 400-line ProcessOrder method into small, named steps without altering a single business rule.
Refactoring goal: readability — make the code communicate its intent without changing what it does.
Change how the code is built — never what the code does. If a transformation cannot be made safely with the available information, leave that code unchanged and say why.

EXISTING CODE CONTEXT
Code context: business-critical — this code implements rules the business depends on.
- Treat every conditional, threshold, and special case as a business rule until proven otherwise — oddities may be load-bearing.
- Do not "fix" behavior that looks wrong; flag it as a question instead. Surprising behavior may be a requirement.
- Prefer transformations that keep the business rules visibly intact and reviewable by a domain expert.
Language: not specified — infer it from the code and stay consistent with it.
Stated constraints:
- Order state transitions must happen in exactly the current sequence
Code to refactor:
```
[Paste the code to refactor here]
```

REFACTORING GOAL
Primary goal: Readability.
Transformation priorities for this goal:
1. Rename for clarity: variables, functions, and types should say what they mean — a reader should not have to reverse-engineer intent.
2. Extract small, well-named functions from long blocks — each doing one nameable thing.
3. Make intent explicit: replace clever constructs and magic values with code that states what it is doing.
4. Reduce the reader's working memory: fewer things to track at once, shorter distance between definition and use.

RISK PROFILE
Risk level: Balanced.
- Apply reasonable improvements: moderate restructuring is allowed where the benefit is clear.
- Group related changes, but keep each group reviewable and separately verifiable.
- When a transformation is borderline-safe, apply the conservative version and note the more aggressive option.

SAFETY RULES
These rules apply to every transformation, at every risk level:
1. Identify behavior assumptions before changing code — list every assumption you rely on.
2. Flag uncertain behavior instead of deciding it: if you cannot tell what a branch does or why it exists, ask — do not guess.
3. Do not remove functionality. Code that looks redundant may be load-bearing.
4. Do not invent requirements. Refactor toward the stated goal, not toward an imagined better product.
5. Do not rewrite unrelated code. Touch only what the goal requires.
6. Explain why each change exists — every transformation traces to the stated goal or to a named problem in the code.
7. Preserve public contracts — signatures, return types, error types, serialized shapes — unless explicitly instructed otherwise.

TRANSFORMATION GUIDANCE
Known failure modes of this goal — watch for:
- A rename is a behavior risk at every call site — trace every reference, including reflection, serialization, and string-based lookups.
- Do not "clean up" expressions you do not fully understand — readability refactors fail when they simplify semantics, not just syntax.

BEHAVIOR PRESERVATION REQUIREMENTS
- Preserve observable behavior: the same inputs produce the same outputs, including error cases.
- Preserve business rules: every condition, threshold, and special case survives the refactor exactly.
- Preserve outputs: formats, ordering, precision, and encodings stay identical unless the goal explicitly targets them.
- Preserve side effects: writes, emitted events, log lines other systems consume — and their relative order.
- Preserve integrations: API shapes, serialized payloads, database access patterns, and external call sequences.
- These requirements hold unless the instructions explicitly say otherwise — and any knowingly behavior-affecting change must be flagged, never silent.
- If achieving the goal and preserving behavior conflict, behavior wins: stop and explain the conflict instead of compromising it.

VALIDATION STRATEGY
Goal-specific validation: renames and extractions must be reference-complete — verify every call site, override, and string-based reference was updated.
- Provide a before/after verification plan: the specific inputs to run against both versions and the outputs that must match.
- Provide a behavior comparison: for each changed unit, the observable behaviors it had before and the evidence each is intact after.
- Provide regression validation: the existing tests that must pass, and the missing tests that should exist before this refactor ships.
- Provide integration verification: every external touchpoint — API consumers, database, events, files — and how to confirm each still sees identical behavior.

ASSUMPTIONS
- List every assumption made about the code's behavior, inputs, or environment.
- Mark each assumption VERIFIED (with its evidence) or UNVERIFIED (with the question that would resolve it).
- Any transformation that depends on an UNVERIFIED assumption must be flagged as conditional on it.

NON-GOALS
- Do not invent requirements.
- Do not redesign the entire system.
- Do not remove behavior without justification.
- Do not introduce new features.
- Separate assumptions clearly from facts.
- Flag uncertainty instead of resolving it silently.
- Explain the tradeoffs of any change that has them.

OUTPUT REQUIREMENTS
- Return the refactored code, complete — no elided sections, no "rest unchanged" placeholders inside changed units.
- Follow it with a change list: for each change — what changed, why it serves the goal, and its behavior impact (expected: none).
- Flag any change that could plausibly alter behavior, with the reason it might and the check that would confirm it does not.
- Where a worthwhile transformation was skipped for safety, list it under "Suggested but not applied" with what information would unlock it.

More resources from Refactor Prompt Builder

Resource

Safe Refactoring Prompt — Zero Regression Tolerance

For code that ships weekly: a refactoring prompt where regression avoidance outranks improvement depth, log lines stay intact, and every step is rollback-friendly.

Prompt Engineering

Resource

AI-Generated Code Cleanup — Deflate the Generated Bloat

Generated code duplicates instead of extracting, wraps without deciding, and defends against impossible states. This prompt hunts those exact failure modes — without preserving bugs as behavior.

Prompt Engineering

Resource

Architecture Cleanup Prompt — Boundaries Without a Redesign

Dependency cycles, leaky modules, misplaced responsibilities — cleaned up within the existing design. Explicitly not an invitation to invent a new architecture.

Prompt Engineering

Resources that pair well

Resource

Code Review Prompt — the Review Contract

"Review this code" gets shallow comments. The review contract gets findings with severities, a checklist, and a verdict.

Prompt Engineering

Resource

Playwright Test Prompt

getByRole over CSS chains, auto-wait over sleep, web-first assertions — Playwright tests written the way Playwright wants.

Engineering

Resource

Debugging Prompt — the Investigation Contract

"Fix this error" gets guesses. The investigation contract gets a ten-stage diagnosis: facts separated from assumptions, alternatives weighed, fixes justified.

Prompt Engineering

Related tools

Tool

Refactor Prompt Builder

Build behavior-preserving refactor prompts — goal, risk level, and code context turn into a safe refactoring contract.

Coding Workflows

Tip: Save time by exploring related resources and tools that integrate with this resource.