Refactoring safely at scale

What you’ll be able to do

Take on a refactor that touches many files, such as renaming a concept, extracting a module or replacing a library, without ever leaving the build broken.

The strategy

1. Pin behaviour: make sure tests cover what you’re about to change
2. Plan in plan mode: list the steps, each small and independently verifiable
3. Write the plan to a file as a checklist
4. Do one step at a time: change, run the tests, commit
5. Review the whole diff at the end against the original goal

Exercise: extract and rename

In a project of your own, or in loop-practice after adding a few more helpers, pick a refactor. For example:

“All string helpers live in the repo root. Move them into src/strings/, one file per helper, with an index.js that re-exports them. Update every import.”

Step 1: Pin behaviour

Before we refactor: check the test coverage for all string helpers. Add
characterization tests for any behaviour that isn't covered yet. Don't
change implementation code.

Commit the tests.

Step 2: Plan

Switch to plan mode (Shift+Tab) and ask:

Plan the move into src/strings/ as a numbered checklist of small steps. Each
step must leave all tests passing. Write it to docs/plans/strings-refactor.md.

Step 3: Carry it out step by step

Do step 1 of @docs/plans/strings-refactor.md. Run the tests, tick the box,
and stop.

Review it, commit it, and repeat. After a couple of steps, if you trust the pattern:

Continue with the remaining steps one at a time. Run the tests after each
step and commit with a message naming the step. Stop if anything fails.

Useful refactoring prompts

• “Find every caller of getUser (including dynamic or string references) before we change its signature.”
• “Rename Customer to Account everywhere, including tests, docs and comments, but not database column names.”
• “Replace moment with date-fns. Start with a table mapping each moment call we use to its replacement.”

Safety nets

• Checkpoints: if a step goes wrong, Esc Esc → Restore code takes you back to before that prompt. Committing after each step gives you a second, permanent net.
• Worktrees: for a risky refactor, run it in an isolated copy with claude --worktree strings-refactor (Module 7). Your main checkout stays untouched until you merge.
• Many mechanical edits? The bundled /batch skill splits a large change across parallel subagents, each in its own worktree.

Red flags to watch for

• Tests changed in the same commit as the refactor. Ask why.
• Files changed that the plan didn’t mention.
• “I also improved…”: unrequested changes make review harder. Ask Claude to keep them for a separate PR.

Verify it worked

• Characterization tests were committed before any refactoring
• A plan file with a checklist exists, and every item is ticked
• Git history shows small commits, one per step, each with passing tests