ع
Start Topics Teams Reference What's new Saved
playbook

Refactor safely behind a green suite

Clean up a gnarly file without changing behaviour — using the test suite as your seatbelt, running it before and after so you can prove nothing broke instead of hoping.

medium ~30 min
when to reach for this

A file has grown into a mess — a 400-line function, duplicated logic, names that lie. It's the file everyone on the team quietly routes around: too central to delete, too tangled to touch, so the workarounds pile up instead. You want it cleaner, but "refactor" without a safety net is just "rewrite and pray." This system makes the test suite the seatbelt: green before, green after, with the structural change in between — so "I didn't change behaviour" is a fact you proved, not a hope you have.

gather this first
  • The file you want to refactor — open the project folder in Claude Desktop and point at it in the chat.
  • A passing test suite that covers the code — if there isn't one, run the backfill-tests playbook first. The seatbelt has to exist before you drive.
  • The test command, so Claude can run it before and after and show you both results — running it is a Power Track step (a terminal-enabled session); if you'd rather, run it yourself and paste both results in.
the workflow

  1. Establish green, then name the smells

    Prove the starting state is green first — that's your baseline (the run-the-suite half is the Power-Track piece; the rest is plain Desktop chat). Then get a plan for what to change before any code moves.

    you ask
    First run the test suite and confirm it's green — that's our baseline. Then read this file and tell me the three biggest structural problems and how you'd fix each, in order, without changing behaviour. Don't refactor yet.

    what you get back A confirmed-green baseline plus a short, ordered plan — "extract the validation into its own function, collapse the duplicated branches, rename data to what it actually holds" — all behaviour-preserving.

    It's far cheaper to correct a wrong approach in prose than in a 300-line diff. Read the plan before it writes a line.

  2. Refactor in small, reviewable moves

    Do the changes as discrete steps, not one giant rewrite — so if something breaks, you know exactly which move did it. In Claude Desktop each step lands as a visual diff you accept or reject in the file pane, which is exactly the step-by-step review you want here.

    you ask
    Do the refactor as separate, small steps in the order we agreed. Behaviour must not change. After each step, show me the diff for that step so I can follow what moved.

    what you get back A sequence of focused diffs — extract, then dedupe, then rename — each one easy to read and accept one at a time, instead of one unreviewable wall of changes.

  3. Prove behaviour is unchanged

    Run the same suite again. Same green is the whole point — it's the difference between "I refactored" and "I rewrote and hoped."

    you ask
    Run the full suite again and show me the result next to the baseline. If anything is red, that's a behaviour change — revert that step and tell me what it touched. Don't paper over a failure.

    what you get back The same green you started with. If a test went red, an honest "step 2 changed behaviour here" and a revert — not a quietly-edited test to make it pass.

    Never take "behaviour is unchanged" on its word — the re-run of the suite is what makes it true. Re-running it is the Power-Track half; if you ran the baseline yourself, run it again yourself and paste the result so the before/after comparison is honest.

  4. Walk me through what changed and why

    End with a short narrative so your eventual reviewer (and future you) understands the intent behind the diff.

    you ask
    Summarize what you changed and why, in a few bullets I could paste into the PR description — what's cleaner now and what behaviour stayed identical.

    what you get back A tight changelog you can drop straight into the PR, so the reviewer reads intent, not just a diff.

make it your own
  • No suite yet: don't refactor blind. Run the backfill-tests playbook to add characterization tests first, then come back here — establishing the suite is the prerequisite, not an optional warm-up.
  • Part of a bigger modernization: a safe refactor is the unit move inside a large replatform — when you're modernizing a whole subsystem, each behaviour-preserving cleanup here is one reviewable step in that arc. See the modernize-subsystem playbook for the orchestration; this playbook is how each individual move stays honest. Behaviour-preserving still means you read the diff — you're the author of record on every step.
  • Bigger reshape: for a structural change across several files, ask for the plan in plan mode first and approve it before any edits — see /features/plan-mode/.
watch out for
  • The green suite is your seatbelt — actually fasten it. Make Claude run the tests before and after; never take its word that behaviour is unchanged, because "looks equivalent" and "is equivalent" are different claims and only the re-run proves the second. The two green runs are the entire safety guarantee — don't skip either. And if coverage is thin, you don't have a seatbelt yet: run the backfill-tests playbook first, then come back.
  • If it suggests a behaviour change "while we're in here," stop and split it out. Mixing a refactor with a behaviour change means a red test could be either, and you've lost the seatbelt.
  • Don't let it edit a test to make a refactor's failure go away. A red test after a behaviour-preserving change is a real signal — listen to it.

you'll end up with A gnarly file becomes a clean one, with the same green suite proving behaviour never moved — a refactor you can stand behind in review instead of a rewrite you're quietly nervous about.

Questions people ask

Do I need an existing test suite before I can use this playbook?
Yes — the test suite is the entire safety guarantee. If the code isn't covered, run the `backfill-tests` playbook first to add characterization tests, then come back here. A refactor with no suite to run before and after is just a rewrite with a nicer name. The reading, planning, and refactor diffs all happen in Claude Desktop; only running the suite before and after is a Power-Track step (a terminal-enabled session, or you run it yourself and paste both results).
What if a test goes red after the refactor?
That's the system working correctly, not a failure. A red test after a behaviour-preserving change is a real signal — ask Claude to identify which specific step caused it, revert that step, and re-examine the approach. Never let it edit the test to make the failure go away.
How do I keep Claude from sneaking in behaviour changes while refactoring?
Two guards: ask for the plan in prose first and read it before any code moves, and ask for each change as a separate, small diff so you can see exactly what each step did. If it ever suggests a behaviour change "while we're in here," stop and split it into a separate PR.
Can I use this for a structural change that spans several files, not just one?
For a multi-file reshape, use plan mode first — ask for the full plan and approve it before any edits are made. The single-file version of this playbook assumes the scope is contained; larger reshapes need the extra approval gate that plan mode provides.