Refactor Plan Prompt: Safe, Step-by-Step Refactoring

Use this prompt before any refactor larger than a rename. It makes Claude describe what the code does today, name the risks, and break the work into small steps that each keep the build green. You approve the plan, then execute it.

The prompt

You are a staff engineer planning a behavior-preserving refactor. The plan will be executed step by step by another engineer (or by you in a later turn), so each step must be small, reversible and verifiable.

<code>
{{CODE_OR_FILE_LIST}}
</code>

<goal>
What I want to improve: {{REFACTOR_GOAL}}
Constraints: {{CONSTRAINTS}}
How we verify behavior today (test command, manual checks): {{VERIFICATION}}
</goal>

<instructions>
1. First describe the current behavior and structure in plain language. Base this only on the code provided; mark anything you are inferring as "Assumption".
2. List the risks: hidden callers, side effects, shared state, public APIs, serialization formats, performance-sensitive paths.
3. If there are no tests covering the behavior, make the first step adding characterization tests.
4. Propose the refactor as numbered steps. Each step must leave the code compiling and tests passing, and should be small enough for one commit.
5. If the goal is ambiguous or the code you need is missing, ask up to 3 questions instead of planning around guesses.
6. Do not write the full implementation. Short snippets to illustrate a step are fine.
</instructions>

<output_format>
## Current behavior
## Assumptions
## Risks (with likelihood: low / medium / high)
## Plan
Numbered steps. For each: change, files touched, how to verify, rollback.
## Out of scope
Things you noticed but are deliberately not changing.
</output_format>

How to use it

• claude.ai: paste the code (or the relevant files) into the code block. For large modules, attach files to a Project instead.
• Claude Code: switch to plan mode with Shift+Tab, then paste the prompt with a file list such as src/billing/* instead of code. Claude reads the files itself. To reuse it, save it as a skill in .claude/skills/refactor-plan/SKILL.md with $ARGUMENTS for the goal; see the skills guide.
• API: send the code in the first part of the user message, with the instructions after it.

Variables

Variable	What to put there
{{CODE_OR_FILE_LIST}}	Source code, or file paths when Claude can read them
{{REFACTOR_GOAL}}	For example “split the 900-line OrderService into smaller units”
{{CONSTRAINTS}}	Public API must not change, no new dependencies, deadline
{{VERIFICATION}}	npm test, a smoke script, a manual checklist

Example output (illustrative)

## Plan
1. Add characterization tests for OrderService.calculateTotal (discounts, tax, empty cart).
   Verify: npm test passes. Rollback: delete the test file.
2. Extract tax logic into TaxCalculator with no behavior change; OrderService delegates to it.
   Verify: same tests pass. Rollback: revert commit.

Tips and variations

• Execution turn: after approving, prompt “Implement step 1 only, run the tests, show the output, then stop.”
• Big codebases: ask Claude to use subagents to explore callers first; see the subagents guide.
• Review the result: run the code review prompt on each step’s diff.