Prompt Engineering

Legacy Code Refactor — Changing Code You Can't Fully See

Legacy code has callers you cannot see and assumptions nobody wrote down. This refactoring prompt treats every public surface as load-bearing and changes in small, verified steps.

Open in Refactor Prompt Builder

Overview

Refactoring legacy code fails differently: the danger is not what the code says, it is what depends on it invisibly. This prompt configures the contract for that reality — the legacy context assumes unknown dependencies and hidden assumptions, treats every public surface as load-bearing, demands incremental change with verification between steps, and requires the model to document every assumption it had to make about unclear behavior. Combined with a conservative risk profile, frozen-schema constraints, and a strict validation plan, the result is a refactor that respects what a twelve-year-old system actually is.

How to use this resource

Assume the unseen

Unknown callers, hidden assumptions, undocumented consumers — the contract treats them as existing, not hypothetical.
State the frozen ground

Public API stays, schema stays — constraints carried as hard rules, not preferences.
Collect the assumption ledger

Every assumption about unclear behavior arrives documented — each one is a risk to verify before merging.

Why This Works

Legacy failures come from invisible consumers — naming that risk changes the transformation choices
Incremental steps with verification beat one sweeping rewrite on unmapped terrain
A documented assumption can be checked; an undocumented one becomes an outage

Best for

Systems with consumers nobody fully maps anymore
Code where the comments stopped being true years ago
Teams inheriting unfamiliar codebases

Not for

Understanding what the legacy code does first — that's the Code Explanation Prompt space
A ground-up rewrite — the contract explicitly forbids redesigning the system

Use cases

Modular cleanup inside a decade-old system
Refactoring around a frozen database schema
Restructuring code whose original authors are gone

FAQ

How does this prompt handle callers I can't see when I don't know who consumes the legacy module?

It treats every public surface as load-bearing — the EXISTING CODE CONTEXT line 'assume unknown dependencies and hidden assumptions' tells the model that code this old has callers you cannot see, so signatures, return types, error types, and serialized shapes stay preserved rather than guessed. You generate that contract as a prompt and run it in ChatGPT, Claude, or Gemini; confirming who actually calls the module stays your job.

How does it flag an assumption about the order module's behavior it cannot confirm?

The ASSUMPTIONS section makes it mark each one VERIFIED with evidence or UNVERIFIED with the question that would resolve it, and any transformation depending on an UNVERIFIED assumption gets flagged as conditional on it. It surfaces those open questions in the output; it can't run the code to settle them, so checking each ledger entry before you merge remains yours.

How do I keep the frozen database schema and OrderService API locked while it restructures the internals?

Both live under Stated constraints ('Public API of OrderService must not change', 'Database schema is frozen') and the Conservative risk profile that keeps every public contract and observable behavior exactly as-is. If the goal and behavior collide, its rule is 'behavior wins' — it stops and explains instead of compromising. Enforcing those frozen boundaries at merge time is still your call.

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
Refactor the order management module of a twelve-year-old system for maintainability without breaking consumers we cannot see.
Refactoring goal: maintainability — make the next change cheaper without changing current behavior.
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: legacy — assume unknown dependencies and hidden assumptions.
- Code this old has callers and consumers you cannot see — treat every public surface as load-bearing.
- Change incrementally: small steps with verification between them, never a sweeping rewrite.
- Document every assumption you had to make about unclear behavior — each one is a risk to verify.
Language: not specified — infer it from the code and stay consistent with it.
Stated constraints:
- Public API of OrderService must not change
- Database schema is frozen
Code to refactor:
```
[Paste the code to refactor here]
```

REFACTORING GOAL
Primary goal: Maintainability.
Transformation priorities for this goal:
1. Separate concerns: split code that changes for different reasons into units that change for one reason.
2. Reduce duplication by extracting the shared logic — once duplication is gone, a future fix lands in one place.
3. Clarify responsibilities: one job per function, one purpose per module.
4. Localize change impact: a future edit should touch few places, not many.

RISK PROFILE
Risk level: Conservative.
- Treat this as production code with low risk tolerance: make the smallest change set that achieves the goal.
- Prefer many small, independently safe transformations over one large restructuring.
- Skip any transformation whose safety cannot be established from the code in front of you — list it as a suggestion instead.
- Keep every public contract, signature, and observable behavior exactly as it is.

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:
- Near-duplicate code is not always true duplication — merging two similar blocks that evolve for different reasons creates coupling, not reuse.
- Do not abstract for imagined future requirements — extract what is duplicated now, not what might vary someday.

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: every extraction and merge must preserve each original call path's behavior, including its edge cases.
- 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

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.

Prompt Engineering

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

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

Projects that use this resource

Project

Modernize a Legacy Codebase with AI

The full path to taming an inherited codebase — understand it, document its architecture, pin its behavior with tests, then refactor, modernize, review, speed up, and ship it without breaking what works.

8 stages Software Development

Workflows that use this resource

Workflow

AI Legacy Code Modernization Workflow

Update old, risky code you didn't write — safely — by understanding and pinning its behavior in tests before you change a single line.

4 steps 45–90 minutes

Guides for this resource

Guide

Refactor Code With AI Without Changing Behavior

"Refactor this to be cleaner" returns tidier code that quietly changed the null handling and an error type — a silent regression. Here's how to refactor with AI without changing behavior: name a small goal, list what must stay identical, forbid fixes, and verify the diff.

Software Development with AI

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