Claude Code refactor prompt: one module, plan first, same behavior

Refactors go wrong when the agent changes structure and behavior in the same pass, and nobody can tell which edit broke what. This work order splits the job in two. First Claude records a test baseline, finds every caller, and writes a step plan. Nothing gets edited until you approve it. Then it makes one small move at a time and runs the tests after each.

The work order

Copy it, fill in the [brackets], and paste it into Claude Code. It also works in Cursor's Agent mode.

Refactor one module safely Claude Code · refactoring

I want to refactor [module or file path]. Behavior must stay exactly the same.

Why: [what's wrong today, e.g. "one 900-line file that mixes parsing and network calls"]
Done looks like: [target shape, e.g. "parsing in its own file, no function over 60 lines"]
Off limits: [public API, file names other code imports, database schema, config keys]

Phase 1, plan only. No edits.
- Run [test command] and record the result as the baseline. If tests already fail, stop and tell me.
- List every caller of this module from outside its folder, with file:line.
- Tell me how well the current tests cover the code you'll be moving. If coverage is thin, propose a few tests to add first that lock in today's behavior.
- Write a numbered plan. Each step is one small move that shouldn't change behavior (extract a function, move a file, rename something internal, inline a helper), and says which check you'll run after it.
Stop and wait for my OK.

Phase 2, after I approve:
- One step at a time. Run the tests after every step.
- If a test fails, undo that step and tell me what happened. Don't patch around it.
- Don't change test assertions. Don't slip in bug fixes or style cleanups; list them for later instead.
- [If commits are fine: commit after each green step as "refactor: <step>".]

Finish with: steps done, the final test result next to the baseline, and the list of things you noticed but left alone.

Start this in plan mode so phase 1 can't edit files by accident. Approve the plan, then switch modes for phase 2.

Variations

Variation 1: Plan only, for a big legacy file No edits

Read [file] and write a refactor plan to [docs/plans/refactor-name.md]. Don't change code.

Cover: what the file does today in plain words, the natural seams where it could be split, the order you'd do it in, which steps are risky and why, and the tests we'd need before starting. Keep it to one page so a teammate can review it in ten minutes.

Handy when the refactor will happen over several sessions or be done by someone else. A fresh session can pick up the plan file.

Variation 2: Rename something used everywhere Repo-wide

Rename [old name] to [new name] across the repo.

Start by listing every reference, including the ones a plain text search can miss: strings, config files, docs, serialized data, and anything looked up by name at runtime. Show me the list and wait. After I approve, make the change, run [typecheck] and [tests], and list any reference you chose not to rename, with the reason.

Variation 3: Lock in behavior before you touch it Safety net

Before we refactor [module], write tests that record what it does today: normal inputs, edge cases, and error paths, even where the current behavior looks wrong. Add a comment "current behavior, check before changing" on the odd ones.

Run them against the untouched code and show they pass. Don't change the module.

When to use it

One file or module has become hard to work in, and the fix is structural, not a feature.
Other code depends on it, so a silent behavior change would hurt.
You want to review the approach before any code moves.
Skip it for a ten-line cleanup. A one-sentence ask is fine there.

What good output looks like

A baseline test run recorded before any edits.
A caller list with real file:line references, not "used in a few places".
Plan steps small enough that each one could be its own commit.
After phase 2, test results that match the baseline, with no assertion changes in the diff.
A separate list of bugs and oddities it found and deliberately didn't fix.

Common mistakes

Asking for "cleaner code" without saying what done looks like. Claude will keep finding things to tidy.
Letting it fix bugs during the refactor. Now a behavior change is hiding inside a diff you were told was safe.
Skipping the baseline. If tests were already red, you can't tell what the refactor broke.
Approving the plan without reading the caller list. That's where breakage usually hides.
Running both phases in one long session. If context gets heavy, save the plan to a file and start phase 2 fresh.

Need a different prompt? Describe your coding goal and get ranked prompts with quality, match & confidence scores.

Rank prompts for my goal →

More Claude Code work orders

Related prompts in the library

FAQ

Should Claude Code refactor in plan mode?

Use plan mode for the first phase, when it reads code and writes the plan, so it can't edit anything. Switch out of plan mode once you've approved the steps and want it to make changes.

What if there are no tests for the module?

Then the first plan step should be adding tests that lock in today's behavior. The third variation above does exactly that. Refactoring untested code with an agent is how behavior changes slip through unnoticed.

Should it commit after every step?

If you're on a branch and comfortable with it, yes. Small commits make it easy to find and revert the one step that broke something. If you'd rather commit yourself, drop that line from the prompt.

Can I refactor several modules at once with this?

You can, but it gets much harder to review. Run it per module. If the modules depend on each other, have Claude write one plan covering the order and then run each module as its own session.