Refactor (Behavior-Preserving)
Restructure code without changing behavior, proven green by tests, scoped to what you touched. No bugfixes smuggled into a 'cleanup'.
v1.0.0 · ~545 tokens · ⬇ 0 · Updated July 6, 2026
What it does
Behavior-preserving refactor with preconditions (safety net + bounded scope), one small named change at a time, tests green between each, commit at checkpoints. Refuses smuggled behavior changes and cosmetic churn. Writes characterization tests first when coverage is missing.
Example uses
Untangle a giant function
A core function has grown into a 300-line nesting mess and you want it readable without changing what it does.
Refactor processWebhookEvent() in src/webhooks/handler.ts — it's around 300 lines with five levels of nesting. Behavior-preserving only: if coverage is thin, write characterization tests first, then extract one cohesive step at a time with a green test run between each. Don't touch the other webhook files.Deduplicate drifting copies
The same logic is copy-pasted across several handlers and the copies have started to drift apart.
Three of our Express route handlers each carry their own copy of the address-validation logic, and they've started to drift. Consolidate them into one named function without changing any endpoint's behavior — run the tests between each step, and if the copies genuinely differ in intent, flag it instead of silently picking one.Clean up before a feature
You need to add a feature to messy code and want the structural cleanup done first, as its own reviewed change.
I need to add multi-currency support to src/pricing/calculator.ts next week, but right now it's full of magic numbers and unclear names. Do a pure structural cleanup first — renames, extracted helpers, named constants — as its own commit series. No behavior changes and no bugfixes smuggled in.Install
# 1. Create the skill folder in your Claude setup mkdir -p ~/.claude/skills/refactor-behavior-preserving # 2. Download SKILL.md into it (or move the file you just downloaded) # → ~/.claude/skills/refactor-behavior-preserving/SKILL.md # 3. Claude Code auto-discovers it on next launch.
Inside the skill
--- name: refactor-behavior-preserving description: Refactor or simplify code without changing behavior, verified by tests. Use when cleaning up, reducing duplication, improving structure, or when the user says "refactor this", "simplify", "clean this up", "improve the architecture". Scoped and safe by construction. --- # Refactor (behavior-preserving) Refactoring changes structure, never behavior. If behavior changes, it's not a refactor — it's a rewrite, and it needs its own review. Stay scoped and stay green. ## Preconditions (don't start without these) - **A safety net exists.** Tests cover the code you're about to move. If they don't, write characterization tests FIRST (capture current behavior, even if "wrong") — then refactor. - **Scope is bounded.** Refactor what's in front of you (the file/function you touched), not the whole codebase. Sweeping refactors hide behind "cleanup" and break things far away. ## The move 1. Run tests → green baseline. 2. Make ONE structural change (extract function, rename, dedupe, invert a condition, replace a magic value). Small and named. 3. Run tests → still green. If red, revert THIS step (not the whole session) and rethink. 4. Repeat. Commit at green checkpoints so you can always fall back. ## High-value, low-risk targets - Duplicated logic → one named function (only if the duplicates are truly the same intent). - Deep nesting → early returns / guard clauses. - Magic numbers/strings → named constants. - Long function → extract cohesive steps with intention-revealing names. - Unclear name → precise name (the cheapest, highest-value refactor there is). ## Guardrails - **No behavior change smuggled in.** No "while I'm here" bugfixes or feature tweaks — do those as separate, reviewed changes. One kind of change per commit. - Don't refactor for its own sake. If the code is clear and stable, leave it. Churn has cost (review, risk, blame history) and cosmetic churn buys nothing. - Preserve the public interface unless the task is explicitly an interface change. ## Output Report: what changed structurally, what stayed identical (behavior/interface), and the green test run that proves it.
Changelog
- v1.0.02026-07-03Initial clean-room write.
Frequently asked questions
Is Refactor (Behavior-Preserving) free?
Yes. Refactor (Behavior-Preserving) is free to download and MIT-licensed.
Where do I install Refactor (Behavior-Preserving)?
Place the SKILL.md file in ~/.claude/skills/refactor-behavior-preserving/ and Claude Code auto-discovers it on next launch.
How many tokens does Refactor (Behavior-Preserving) use?
About 545 tokens — it is designed to be token-lean.
We're developers and SaaS builders who use these tools daily in production. Every review comes from hands-on experience building real products — DealPropFirm, ThePlanetIndicator, PropFirmsCodes, and many more. We don't just review tools — we build and ship with them every day.
Written and tested by developers who build with these tools daily.