Claude Code Prompt for Refactoring: 12 Safe-Step Prompts
12 Claude Code prompts for refactoring: start in plan mode, pin behavior with tests, run a baseline, change code in small steps and stop when tests go red.

A Claude Code prompt for refactoring should make Claude Code plan before it edits, prove the tests are green before it starts, and change the code in small steps with a test run after each one. Claude Code can read your whole repository and run your test command, so the prompt's job is to set limits: what must not change, when to stop, and what done looks like. Below are 12 prompts for refactoring with Claude Code, plus a worked plan for a 400-line billing function.
The Claude Code refactoring prompt with plan mode, tests and safe steps gives you a read-only map, coverage gaps with characterization tests, a baseline run, numbered steps with risks, execution rules, per-step reports and finish checks.
Set up the session
Start in plan mode with claude --permission-mode plan, or press Shift+Tab until the status bar shows plan mode. Claude Code reads files and proposes a plan without editing until you approve. Keep repo conventions in CLAUDE.md so every session follows them, and work on a branch.
Understand before changing
1. Map the target
Without editing anything, explain what [file or function] does, list every caller in the repo, and list the tests that cover it.
2. Find coverage gaps
Which behaviors in [target] have no test? Propose characterization tests that pin current behavior, including odd behavior, with expected values recorded from the current code.
3. Map callers with a subagent
Use a subagent to find every usage of [function or class] and report only the call sites and how each uses the return value.
Plan the refactor
4. Baseline run
Run [test command] and report exact pass and fail counts. If anything fails, stop and show me before planning.
5. Step plan with risks
Plan a refactor of [target] to fix [smell] in steps small enough to review in one diff each. Give the risk of each step and keep [boundaries] unchanged.
6. Boundaries check
List the public signatures, return shapes and files this refactor must not change, and tell me how you will verify each at the end.
Execute in small steps
7. One step at a time
Do step [number] only. Run [test command] after it, then summarize the diff and the test result. Do not start the next step.
8. Stop on red
The tests failed after the last step. Show the failing test and the diff, explain the cause, and propose either a fix or rewinding the step. Do not edit the test.
9. Remove duplication safely
These blocks look duplicated [locations]. Before merging them, write tests showing whether they behave the same on [inputs]. Merge only the ones that do.
Finish and hand off
10. Finish checks
Confirm signatures and return values match main, callers and protected files are untouched, and tests and linter pass. Report anything that changed outside the plan.
11. Commits and PR notes
Suggest one commit message per step and a short PR description: what moved, what did not change, and suspected bugs left for later.
12. Flagship: refactor with plan mode and tests
Target [file or function], Smell [what is wrong], TestCommand [command], Boundaries [what must not change], DoneWhen [definition of done], RepoRules [conventions or CLAUDE.md]. Map read-only, find coverage gaps, run a baseline, plan small steps, execute one at a time with tests, stop on red, and finish with boundary checks and commits.
Worked example: a 400-line build_invoice()
In the flagship example, the target is a billing function that computes line totals, applies discounts, calculates regional tax and builds the data for a legacy PDF renderer. The read-only map finds two callers and one end-to-end test file. The key find is in the coverage gaps: the three rounding blocks are not identical, so merging them could change invoice totals by a cent. The plan adds characterization tests first, extracts four helpers one step at a time, and merges the rounding only if the new tests show it is safe. The cent difference is listed as a suspected bug, not silently fixed.
Undo and safety
- Claude Code checkpoints its file edits. Run /rewind, or press Esc twice with an empty prompt, to restore code, conversation or both to an earlier point.
- Files changed only by Bash commands are not tracked by checkpoints, and checkpoints do not replace Git. Commit after each green step.
- Do not let Claude Code edit tests to make them pass unless you agree to the change.
- Claude Code is made by Anthropic. PromptDig is an independent prompt library, not affiliated with or endorsed by Anthropic, and the commands here follow the public Claude Code docs at the time of writing.
Variations
- Frontend: ask it to extract components from a large React file and keep props and rendered output the same, with snapshot or testing library checks.
- Rename across a repo: plan the rename, list every file it touches, and run the type checker after each batch.
- Parallel work: run a second session in its own worktree with
claude --worktreeso refactors do not collide.
Related on PromptDig
Using ChatGPT instead? See the ChatGPT prompts for code refactoring. For the steps around a refactor, try the Claude Code prompts for testing and the Claude Code prompts for code review. More in the Agents hub, browse all prompts, or share a Claude Code prompt you rely on.