Coding

Refactoring

Restructure existing code safely without changing behaviour.

Knowledge cards
Knowledge card
Rename for Clarity Before You Restructure
A refactoring sequence where the first pass only improves names — variables, functions, parameters — with no structural change, and only after the code reads clearly do you move or split anything.
L2 · Context engineering
Knowledge card
Extract One Seam at a Time
A refactoring pattern for oversized functions or modules where you have Claude identify the natural seams — self-contained chunks of responsibility — and extract them one at a time, testing after each, rather than rewriting the whole thing in one move.
L3 · Workflows
Knowledge card
Pin the Behaviour With Tests Before You Refactor
A refactoring pattern where, before changing any structure, you have Claude write characterization tests that capture what the code currently does — including its quirks — so you can restructure with a green suite proving you changed nothing observable.
L3 · Workflows
Workflow
Refactor With Claude in Named, Behaviour-Preserving Steps
Refactoring by asking Claude for one named, behaviour-preserving move at a time — extract this function, rename that concept, inline this variable — each verifiable on its own.
L3 · Workflows
Claude for refactoring

Refactor in named, safe steps

The risk in refactoring is changing behaviour while trying only to change structure. Reduce it by asking Claude for named, small steps rather than one sweeping rewrite: 'extract this into a function, behaviour identical', then 'inline that duplicate', then 'rename for clarity'. Each step is easy to review and easy to revert. Vague requests like 'clean this up' invite exactly the silent behaviour changes you want to avoid. Precise, incremental moves keep the refactor honest and the diff readable.

Protect behaviour with tests

Before a meaningful refactor, get the behaviour under test — ask Claude to write tests that capture what the code currently does, then refactor against them. If the tests stay green, the behaviour held; if one breaks, you have caught a regression the moment it happened. This is what makes AI-assisted refactoring safe at scale: you are not trusting that the change preserved behaviour, you are verifying it. Keep each step small enough that a red test points clearly at the cause.

Frequently asked
How do I refactor safely with Claude?

Ask for small, named steps that preserve behaviour — extract, inline, rename — rather than one sweeping rewrite. Each step is easy to review and revert, keeping the refactor honest.

How do I stop refactoring from changing behaviour?

Get the behaviour under test first, then refactor against those tests. Green tests confirm behaviour held; a red one catches a regression immediately.

Why is 'clean this up' a bad refactoring prompt?

It is vague enough to invite silent behaviour changes. Precise, incremental instructions keep the diff readable and the behaviour intact.