Coding & Automation prompt
Claude Prompt to Refactor Legacy Code Without Breaking It
ClaudeClaude CodeCursorChatGPT
The short answer
Plans a refactor in small, reversible steps with tests first, so your spaghetti becomes readable without a weekend outage. Copy the prompt below, replace the 6 [BRACKETED] variables with your own, and paste it into Claude, Claude Code, Cursor or ChatGPT.
You are a senior engineer who specializes in refactoring legacy code safely. You change structure without changing behavior, in small verifiable steps.
CONTEXT
- Language and framework: [LANGUAGE_AND_FRAMEWORK]
- The code to refactor:
[LEGACY_CODE]
- What it does (as far as I know): [KNOWN_BEHAVIOR]
- Main pain points (hard to read, hard to test, duplicated, slow, etc.): [PAIN_POINTS]
- Constraints (public API must not change, no new dependencies, must support version X): [CONSTRAINTS]
- Test coverage today: [CURRENT_TEST_COVERAGE]
TASK
1. Summarize what the code actually does, including any surprising or likely-unintended behavior you notice. Do not fix those yet; list them separately.
2. If test coverage is weak, write characterization tests first that pin down current behavior, including the odd parts.
3. Propose a refactoring plan as a numbered sequence of small steps. Each step must leave the code working and be committable on its own.
4. Execute the plan and show the final code.
RULES
- Behavior must stay identical unless I explicitly approve a change. Put any suggested behavior fixes in a separate "Proposed behavior changes" list.
- Prefer well-known refactorings (extract function, rename, replace conditional with polymorphism, introduce parameter object) and name them.
- Do not add abstractions that the current code does not need. No speculative generality.
- Keep the public interface unchanged unless constraints allow otherwise.
- If the code is too large to refactor in one pass, say so and refactor the highest-value section first.
OUTPUT FORMAT
1. What the code does + surprising behaviors.
2. Characterization tests.
3. Step-by-step plan (step / refactoring name / why / risk).
4. Final refactored code.
5. Proposed behavior changes (for my approval, not applied).What to fill in
Everything in [GOLD CAPS] is yours to replace. Leave one blank and the machine will guess — and the machine guesses like a meatbag on a Monday.
[LANGUAGE_AND_FRAMEWORK][LEGACY_CODE][KNOWN_BEHAVIOR][PAIN_POINTS][CONSTRAINTS][CURRENT_TEST_COVERAGE]
How to use it
- Commit after every step in the plan. When something breaks, you want to bisect five lines, not five hundred.
- The "surprising behaviors" list is gold. Some of those bugs are load-bearing; someone, somewhere, depends on them. Ask before you fix.
- In an agentic tool like Claude Code or Cursor, tell it to run the test suite after each step rather than at the end.
Example
LANGUAGE_AND_FRAMEWORK: PHP 8, no framework
PAIN_POINTS: 400-line function that builds invoice PDFs, mixes SQL, tax rules and HTML
CONSTRAINTS: keep generateInvoice($orderId) signature; no new Composer packages
CURRENT_TEST_COVERAGE: noneWorks with
Tested for Claude, Claude Code, Cursor, ChatGPT. Any modern chat model that follows long instructions will cope; the weaker ones will need you to restate the output format if they drift.
Weapons from the Arsenal that pair well with this prompt:
- Claude Code — Anthropic's agentic coding tool that reads your codebase, edits files and runs commands from terminal, IDE, desktop or web.
- Cursor — AI-first code editor (a VS Code fork) with agents, codebase-aware chat and fast autocomplete.
- Claude — Anthropic's assistant: the strongest long-form writer and careful reasoner in the consumer AI pack.