How to Refactor Code With Claude Code Without Breaking It

Build the fence before you move anything. Commit your current work so the tree is clean, get one test passing that exercises the code you are about to change, and write a single sentence saying what behaviour must be identical afterwards. Then open the Claude Code desktop app, describe the one structural change you want, and refuse everything else. Run the test after each step. Commit after each step. That loop is the whole method, and it is boring on purpose.

Refactoring is the task where agent speed hurts you most. Writing new code has an obvious pass or fail at the end: the feature works or it does not. A refactor has no such signal. The app still runs, the code reads better, the diff looks professional, and the one edge case that used to be handled by a strange-looking conditional is now gone. You find out three weeks later. Everything below exists to make that outcome visible while it is still cheap.

The Fence-First Refactor is the pattern we teach for this, and the name is the instruction. You do not move furniture before you know where the walls are. The fence is three things, all built before you write the first prompt, and each one takes under five minutes.

The contract sentence is the piece people skip and the piece that does the most work. It converts a vague instruction into a checkable one, and it gives you something concrete to hold the finished diff against. It also gives Claude Code a boundary it can reason about instead of guessing at your intent from the shape of the code.

A refactor changes structure and leaves behaviour untouched. A rewrite changes both. Claude Code is extremely good at rewriting and it does not always announce the switch, because from inside the task both look like improving the file. You ask it to extract a function and it also renames three variables, converts a loop to a map, adds a null check that was not there, and removes a branch it judged unreachable. Four of those five are fine. The unreachable branch was reachable on Sundays.

There is a version of this that is not the agent's fault. If your prompt says clean up this file, you have asked for a rewrite and you will get one. The word refactor carries a precise meaning in your head and a fuzzy one in a sentence, so replace it with the actual operation: extract, inline, rename, move, split, or deduplicate. One verb, one target, one commit.

A seam is a place where the code can be cut without touching anything on the other side. Refactoring seam by seam is what turns an unreviewable 900-line diff into six diffs you can actually read. Find the seams before you start and the whole job becomes a sequence of small, verifiable moves rather than one long act of faith.

One seam per session is a good default for anything unfamiliar. Long sessions accumulate context that stops being relevant, and a refactor conversation that started with the parser is a poor place to discuss the database layer. Clear the session between seams and let the commit history carry the memory instead, which is the habit behind [Claude Code context management](/blog/claude-code-context-management).

A good refactor prompt names the operation, the target, the contract, and the verification. Four parts, one message, no ambiguity about what counts as done. Here is the shape, and it works whether the target is a 40-line function or a service class nobody has opened in a year.

That last line matters more than it looks. Without it, a failing test becomes a second, unrequested change made to satisfy the first one, and now you are reviewing a fix to a problem you never saw. Telling it to stop on red turns the test from a hurdle into a tripwire.

You write the test first, and you write it to describe what the code currently does rather than what it should do. That distinction is the whole trick. You are not documenting correct behaviour, you are pinning down existing behaviour, including the bits that look wrong. If the function returns null on an empty array, your test asserts null. Fix it later, in a commit with its own name.

This is also the fastest way to understand code you did not write, because a test that captures real behaviour teaches you more than a summary does. If the file is one of many and the whole codebase is unfamiliar, the wider approach in [Claude Code on a large existing codebase](/blog/claude-code-large-existing-codebase) is the place to start before you pick a file to improve.

Read the diff for what disappeared, not for what appeared. New code announces itself and is easy to judge. Removed lines are quiet, and a refactor is mostly removal. Every deleted conditional, early return, try block and default value is a question you have to answer before you merge.

If the diff is too big to review properly, that is not a reason to skim it. It is a signal that the seam was too wide. Reset to the last commit and cut the job smaller. This is the general discipline in [review Claude Code output before you ship](/blog/review-claude-code-output-before-you-ship), and refactors are the case where it pays the most, because there is no feature to demo that would have caught the mistake.

Here is the whole Fence-First Refactor as a routine. It looks slower than just asking for a cleanup and it is faster in practice, because the time refactoring costs is almost never the editing. It is the week you spend finding out why an old customer's invoices stopped generating.

The branch and the per-seam commits are doing quiet work throughout: they make abandoning a bad attempt completely painless, which is what lets you be aggressive about resetting instead of trying to argue a confused session back on track. The [git workflow for Claude Code](/blog/claude-code-git-workflow) covers that safety net in full, and it is the prerequisite for everything here.