ClaudeRefactoringLevel 3: Workflows

How Do You Refactor With Claude Safely?

Ask for one named move at a time, such as extract, rename or inline, with behavior unchanged. Run the tests and commit after each one. Anthropic's Claude Code docs give the same advice in short form: refactor in small, testable increments, and say the behavior must stay the same.

Prompt to copy
Refactor [file or module] to [goal], keeping behavior exactly the same. Read it and its tests first.

List your planned moves as named steps, such as "extract validateOrder from handleOrder" or "inline formatTotal". Moves only: no bug fixes, no new features, no helpers for one-time use, and no changes outside [scope]. If you spot a bug, note it at the end and leave it alone.

Then do the first move only. Run [test command], show me the output, and stop. Don't edit any test. I'll commit before the next move.
  1. 1Name the move
  2. 2Make only that move
  3. 3Tests pass
  4. 4Commit
Then repeat
A rule of thumb, not an Anthropic chart: if a test goes red, the one move since the last commit is the cause.

Try it now

  1. 1Run your tests once in Claude Code, so you know they pass before you start.
  2. 2Send the prompt, and read the list of moves before you let it continue. Cut any that aren't refactors.
  3. 3After the first move, run /diff, then commit. Reply next move and repeat.
  4. 4It worked if each commit holds one move, no test file changed, and the list of bugs it noticed is waiting for you at the end.

Use it when

Code you plan to keep: long functions, duplication, modules that have become tangled. It needs tests in place. If they don't exist, write characterization tests first. It works best in Claude Code, where Claude can run the tests after each move.

Skip it when

When you actually want new behavior. That isn't a refactor, so treat it as a change with its own review. Skip the step-by-step approach, too, for a mechanical change across many files, which suits /batch better. And don't refactor code you're about to delete.

Why it works

A request like "clean this up" sets no boundary, and how far Claude goes depends partly on effort. Anthropic's Sonnet 5.5 guide says that at xhigh and max, the model can make related fixes it noticed along the way, so it advises running routine work at high or below. Naming the move sets the boundary, and telling Claude to note bugs without fixing them keeps two kinds of change apart. Tests then do the checking. Anthropic's docs say a pass or fail check lets Claude make the change, run it and fix what broke by itself. And since each commit holds one move, a failure has only one suspect.

Example

A 90-line handleOrder validates input, applies discounts and formats the response. The list might read: extract validateOrder, extract applyDiscounts, extract formatOrderResponse, rename d to discount. You'd expect four small commits, each with passing test output. If Claude notices that discounts round the wrong way, that goes on the list and becomes a separate fix.

Going further

Once the moves are done, run /code-review HEAD~4..HEAD to review just those commits, since /code-review takes a commit range and looks for correctness bugs. Be careful with /simplify: it applies cleanups using four parallel review agents, and the docs say it doesn't look for correctness bugs. For a very large migration, Anthropic's write-up describes the same idea at scale: a test harness that runs against old and new code, a small trial run whose output gets thrown away to improve the rules, and any behavior change treated as a bug.

Common mistakes

  • Bundling a bug fix into a refactor. Tests then change for two reasons, and a red result can't tell you which one broke.
  • Running routine refactors at xhigh or max, where Anthropic says the model may take on related fixes and extra rounds of review.
  • Relying on /rewind after a sed command. A file that only a Bash command changed isn't restored, so commit before each move.
  • Letting Claude edit a failing test to get green. Tell it to stop and report instead, because a changed test means behavior may have changed.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Beyond the course