Refactoring
Restructure code one named move at a time, starting with characterization tests when the code has none.
-
Should You Rename Code Before Refactoring It? Yes, if the names are vague. Level 2: ContextSafe in a names-only passNeeds its own plan
- Local variable
- Private function
- Exported name
- Stored JSON key
-
How Do You Break Up a Huge Function With Claude? Have Claude list the function's separate responsibilities in order of risk, then extract only the safest one. Level 3: Workflows
- 1Rank seams by risk
- 2Move the safest onemove it, don't rewrite it
- 3Run the tests
- 4Commitone seam per commit
Repeat until a seam won't separate cleanly -
How Do You Refactor Code That Has No Tests? Have Claude write characterization tests that record what the code does today, quirks included. Level 3: Workflows
- 1Record today's behavior
- 2Prove the tests can fail
- 3Lock the tests
- 4Refactor
-
How Do You Refactor With Claude Safely? Ask for one named move at a time, such as extract, rename or inline, with behavior unchanged. Level 3: Workflows
- 1Name the move
- 2Make only that move
- 3Tests pass
- 4Commit
Then repeat
The order that keeps a refactor safe
Work in this order. First make sure tests exist and can actually fail. Then rename, so the code says what it does. Then extract one piece at a time, committing after each. Each stage makes the next one easier and keeps a failure easy to trace. If your tests go red, the only suspect is the move you just made. Keep bug fixes out, and have Claude list any it notices so you can fix them later as separate changes.
Claude Code's undo has limits
Commit before each move, and don't rely on /rewind alone. Anthropic's docs say it doesn't restore a file that only a Bash command changed, which matters if Claude runs sed across your code. Edits from most subagents aren't restored either. Be careful with /simplify too, since it applies cleanups and doesn't look for correctness bugs. For bugs, use /code-review on your commit range. And keep routine refactors at high effort or below. Anthropic's Sonnet 5.5 guide says the model may make related fixes on its own at xhigh and max.
How do I refactor safely with Claude?
Ask for one named move at a time, such as extract or rename, with behavior unchanged. Run the tests and commit after each one. Tell Claude not to edit tests, and to list any bugs it notices instead of fixing them.
How do I refactor code that has no tests?
Have Claude write characterization tests that record what the code does today, including odd behavior. Then confirm they fail when the code is broken on purpose. Only after that should you start changing the structure.
Why is "clean this up" a bad refactoring prompt?
It sets no boundary, so Claude has to guess what you'd accept, and behavior changes can slip in with structure changes. Name the move and the scope instead, and say that behavior must stay exactly the same.
Can I undo a Claude Code refactor?
Often, with /rewind or by pressing Esc twice on an empty prompt. It doesn't cover files changed only by Bash commands, and most subagent edits aren't restored. Anthropic says it works alongside git rather than replacing it, so commit first.