Do a large refactor in small safe steps

This prompt runs a big refactor, such as swapping a library across the app, in small steps that each leave the app working. The agent tests after every step and stops if anything fails.

text-code-safe-large-refactor — claude code — 90 words

Refactor goal: [e.g. replace our custom fetch wrapper with the official SDK across the app]
Scope: [FOLDERS OR FILES]
Must not change: [e.g. public API, database schema, UI behaviour]

First, find every place this touches and show me the list with a plan split into small steps, each one leaving the app working. Then do one step at a time: make the change, run [TEST AND LINT COMMANDS], and stop if anything fails. Do not mix in unrelated clean-ups. At the end, list anything you left for later and why.

Edit in the builder Copy & open Claude Code ↗Copy & open Cursor ↗

Commit after each step. If step 7 goes wrong, you only lose step 7.

Get a better result

What you will get

A list of every place the change touches, a plan in small steps that each leave the app working, then one step at a time with tests run after each and a note of anything left for later.

Common mistake

The AI starts editing before it has listed the files.

Fix: Keep “find every place first and show me the list”, and add “do not change any file until I say go”.

Also watch for

A step breaks the build and later steps build on it. Name the exact test and lint commands, and say “stop at the first failure and show me the output, do not try to fix it by changing the tests”.
Unrelated clean-ups sneak into the diff. Repeat “change only what the goal needs”. Ask for a short list of side observations instead, so you can decide on them separately.

Try a variation: do a dry run first

Ask the AI to “pick the single smallest file in scope, make the change there only, and show me the diff”. If that one looks right, continue with the rest.

Still not right? Reply with this

Show me the step list again as a table with the files each step touches, how I will check it, and how to undo it if it goes wrong.