Refactor safely

Skill buildmoonshot/skillpacks/skills/engineering/expert/refactor-safely

A beginner-to-expert curriculum of drop-in skills for Claude Code, Codex, and any coding agent. Copy-paste ready, tested, not a link farm.

Install

npx -y skills add buildmoonshot/skillpacks --skill refactor-safely

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when restructuring existing code without intending to change its behavior — extracting functions, renaming across files, splitting modules, or swapping an implementation. Makes the agent pin current behavior with tests first, change in small verified steps, and prove behavior is unchanged, so a "cleanup" never silently breaks something.

SKILL.md

2.0 KB, as published. Nobody here has run it

Refactor Safely

A refactor changes structure, not behavior. The whole risk is changing behavior by accident. Defend against it.

The procedure

Pin the behavior first. Before touching anything, make sure the code you're about to move is covered by tests. If it isn't, write characterization tests that capture what it currently does (even quirks) and get them green. You cannot refactor safely what you cannot observe.
Refactor in small steps. Make one structural change at a time — extract a function, rename a symbol, move a file. Keep each step mechanical and reversible.
Run the tests after every step. Green after each step means the behavior held. If a step goes red, you know exactly which change broke it — revert just that step.
Keep refactor commits separate from behavior changes. Never mix "I reorganized this" with "I also fixed a bug / changed logic" in the same diff. A reviewer should be able to trust a refactor diff changes nothing functional. If you spot a real bug mid-refactor, note it and handle it in its own change.

Signs you've left "refactor" and entered "rewrite"

The tests need to change to keep passing → you're altering behavior, not refactoring. Stop and make that an explicit, separate decision.
The diff is large and you can't point to the equivalent old code for each new line → break it into smaller steps.

Why this matters

"Just cleaning this up" is one of the most common ways working software breaks, because the change feels safe and goes unreviewed. Characterization tests plus small, individually-verified steps turn a risky sweep into a sequence of provably-behavior-preserving moves.