Refactoring Guide
Overview
Refactoring is changing the internal structure of code without changing its observable behavior. The goal is readability, maintainability, and testability — never new features and never bug fixes in the same step.
Keywords: refactor, clean up, simplify, extract function, extract method, extract variable, inline, rename, remove duplication, reduce nesting, decompose conditional, guard clause, god class, long function, code smell, DRY, separation of concerns, make testable, reduce cyclomatic complexity.
The two non-negotiable rules:
- Behavior must not change. No new functionality, no bug fixes, no API changes in a refactoring commit. If you spot a bug, note it and fix it in a separate commit.
- Tests stay green at every step. Refactor in small steps; run tests after each. If there are no tests, write characterization tests first (see
references/characterization-tests.md).
When the task mixes refactoring with feature work, separate them: "make the change easy (this may be hard), then make the easy change." Refactor first, commit, then build the feature.
Workflow
Follow this loop. Do not batch many changes before testing.
Establish a safety net.
- Find and run the existing test suite. Confirm it passes before you touch anything.
- If coverage of the target code is weak or absent, write characterization tests that pin current behavior (including current quirks). See
references/characterization-tests.md.
- Identify how to run the tests fast (single file / single test) so the inner loop is quick.
Identify the smell and pick ONE refactoring.
- Scan the target code against the smell catalog in
references/code-smells.md.
- Map the smell to a refactoring using the table in
references/refactoring-catalog.md.
- Choose the smallest refactoring that improves the worst problem first. Resist doing everything at once.
Apply the smallest mechanical step.
- Prefer automated/IDE refactorings (rename, extract) — they are safer than hand edits.
- Follow the mechanics in
references/refactoring-catalog.md step by step.
- Keep each edit tiny: one extraction, one rename, one guard clause.
Run the tests.
- Green → commit (or stage) immediately with a clear message like
refactor: extract calculateTax from invoiceTotal.
- Red → revert this step (don't debug a half-refactor). Take a smaller step.
Repeat until the smell is gone and the code reads clearly.
Final verification.
- Run the full test suite, linters, and type checker.
- Run
scripts/refactor_check.sh <paths> to confirm public API surface and signatures are unchanged.
- Diff-review: every change should be structure-only. Anything that alters output is a red flag.
Decision Framework: which refactoring?
| If you see... |
Apply |
Mechanics |
| A long function doing several things |
Extract Function |
catalog §1 |
| A cryptic expression |
Extract Variable (explaining variable) |
catalog §2 |
Deep if/else nesting |
Replace Nested Conditional with Guard Clauses |
catalog §4 |
| Same code in 2+ places |
Extract Function + call it (DRY) |
catalog §1, §7 |
| A trivial wrapper that hides nothing |
Inline Function/Variable |
catalog §3 |
| Unclear name |
Rename |
catalog §5 |
| Long parameter list / repeated arg groups |
Introduce Parameter Object |
catalog §6 |
switch/if on a type code, repeated |
Replace Conditional with Polymorphism |
catalog §8 |
| A class that knows/does too much |
Extract Class / Move Method |
catalog §9 |
| Comments explaining what code does |
Extract Function with an intention-revealing name |
catalog §1 |
When unsure, default to Extract Function + Rename — together they resolve most readability smells with the lowest risk.
Best Practices
- Tiny steps, frequent tests. A refactoring session is dozens of safe micro-commits, not one giant rewrite.
- One refactoring per commit. Keeps diffs reviewable and reverts surgical.
- Separate refactoring commits from behavior changes. Never mix. Reviewers should be able to trust a
refactor: commit changes nothing observable.
- Name things for intent, not implementation (
isEligibleForDiscount, not checkFlag2).
- Prefer pure functions when extracting — pass inputs in, return outputs, avoid reaching into shared state.
- Let tests drive trust. If you can't test it, characterize it first; if you can't characterize it, you can't safely refactor it.
- Leave the campsite cleaner. Opportunistic, bounded cleanup around code you're already touching beats a doomed "big refactor" project.
Common Pitfalls
- Refactoring without tests. The #1 way to silently break behavior. Write characterization tests first.
- Mixing in a bug fix or feature. Now the diff can't be trusted as behavior-preserving. Split it out.
- Big-bang rewrite. High risk, hard to review, easy to abandon. Decompose into incremental steps.
- Changing public API while "just refactoring". Renaming/removing exported symbols is a breaking change, not a refactor. Use deprecation shims if needed.
- Over-extraction. Splitting into so many one-line functions that flow is lost. Extract for clarity, not dogma.
- Premature abstraction. Don't DRY up two things that merely look similar; wait for the third real duplication and confirm they change together.
- Not running tests between steps. When something breaks you won't know which step did it.
Bundled resources
references/code-smells.md — catalog of smells with detection signals and the refactoring each implies.references/refactoring-catalog.md — numbered, step-by-step mechanics for each core refactoring, with before/after examples.references/characterization-tests.md — how to pin legacy behavior before refactoring untested code.scripts/refactor_check.sh — verification helper: runs tests + lint/type-check and snapshots exported symbols to detect accidental API changes.examples/extract-function-walkthrough.md — a full worked example from smelly code to clean, step by step.
1---2name: refactoring-guide3description: Applies safe, incremental, behavior-preserving refactorings (extract function/variable, rename, inline, decompose conditionals, remove duplication, replace conditional with polymorphism, introduce parameter object) using a test-protected, small-step workflow. Use this skill when the user asks to "refactor", "clean up", "simplify", "extract a method/function", "rename", "remove duplication", "reduce nesting", "break up a god class/long function", "improve readability", "untangle" code, "make this testable", "reduce complexity", or "tidy up" without changing what the code does. Covers code smell detection, choosing the right refactoring, and verifying behavior is unchanged.4license: MIT5---67# Refactoring Guide89## Overview1011Refactoring is changing the internal structure of code **without changing its observable behavior**. The goal is readability, maintainability, and testability — never new features and never bug fixes in the same step.1213Keywords: refactor, clean up, simplify, extract function, extract method, extract variable, inline, rename, remove duplication, reduce nesting, decompose conditional, guard clause, god class, long function, code smell, DRY, separation of concerns, make testable, reduce cyclomatic complexity.1415The two non-negotiable rules:16171. **Behavior must not change.** No new functionality, no bug fixes, no API changes in a refactoring commit. If you spot a bug, note it and fix it in a **separate** commit.182. **Tests stay green at every step.** Refactor in small steps; run tests after each. If there are no tests, write characterization tests first (see `references/characterization-tests.md`).1920When the task mixes refactoring with feature work, separate them: "make the change easy (this may be hard), then make the easy change." Refactor first, commit, then build the feature.2122## Workflow2324Follow this loop. Do **not** batch many changes before testing.25261. **Establish a safety net.**27 - Find and run the existing test suite. Confirm it passes *before* you touch anything.28 - If coverage of the target code is weak or absent, write characterization tests that pin current behavior (including current quirks). See `references/characterization-tests.md`.29 - Identify how to run the tests fast (single file / single test) so the inner loop is quick.30312. **Identify the smell and pick ONE refactoring.**32 - Scan the target code against the smell catalog in `references/code-smells.md`.33 - Map the smell to a refactoring using the table in `references/refactoring-catalog.md`.34 - Choose the smallest refactoring that improves the worst problem first. Resist doing everything at once.35363. **Apply the smallest mechanical step.**37 - Prefer automated/IDE refactorings (rename, extract) — they are safer than hand edits.38 - Follow the mechanics in `references/refactoring-catalog.md` step by step.39 - Keep each edit tiny: one extraction, one rename, one guard clause.40414. **Run the tests.**42 - Green → commit (or stage) immediately with a clear message like `refactor: extract calculateTax from invoiceTotal`.43 - Red → revert this step (don't debug a half-refactor). Take a smaller step.44455. **Repeat** until the smell is gone and the code reads clearly.46476. **Final verification.**48 - Run the full test suite, linters, and type checker.49 - Run `scripts/refactor_check.sh <paths>` to confirm public API surface and signatures are unchanged.50 - Diff-review: every change should be structure-only. Anything that alters output is a red flag.5152## Decision Framework: which refactoring?5354| If you see... | Apply | Mechanics |55|---|---|---|56| A long function doing several things | Extract Function | catalog §1 |57| A cryptic expression | Extract Variable (explaining variable) | catalog §2 |58| Deep `if/else` nesting | Replace Nested Conditional with Guard Clauses | catalog §4 |59| Same code in 2+ places | Extract Function + call it (DRY) | catalog §1, §7 |60| A trivial wrapper that hides nothing | Inline Function/Variable | catalog §3 |61| Unclear name | Rename | catalog §5 |62| Long parameter list / repeated arg groups | Introduce Parameter Object | catalog §6 |63| `switch`/`if` on a type code, repeated | Replace Conditional with Polymorphism | catalog §8 |64| A class that knows/does too much | Extract Class / Move Method | catalog §9 |65| Comments explaining *what* code does | Extract Function with an intention-revealing name | catalog §1 |6667When unsure, default to **Extract Function** + **Rename** — together they resolve most readability smells with the lowest risk.6869## Best Practices7071- **Tiny steps, frequent tests.** A refactoring session is dozens of safe micro-commits, not one giant rewrite.72- **One refactoring per commit.** Keeps diffs reviewable and reverts surgical.73- **Separate refactoring commits from behavior changes.** Never mix. Reviewers should be able to trust a `refactor:` commit changes nothing observable.74- **Name things for intent**, not implementation (`isEligibleForDiscount`, not `checkFlag2`).75- **Prefer pure functions** when extracting — pass inputs in, return outputs, avoid reaching into shared state.76- **Let tests drive trust.** If you can't test it, characterize it first; if you can't characterize it, you can't safely refactor it.77- **Leave the campsite cleaner.** Opportunistic, bounded cleanup around code you're already touching beats a doomed "big refactor" project.7879## Common Pitfalls8081- **Refactoring without tests.** The #1 way to silently break behavior. Write characterization tests first.82- **Mixing in a bug fix or feature.** Now the diff can't be trusted as behavior-preserving. Split it out.83- **Big-bang rewrite.** High risk, hard to review, easy to abandon. Decompose into incremental steps.84- **Changing public API while "just refactoring".** Renaming/removing exported symbols is a breaking change, not a refactor. Use deprecation shims if needed.85- **Over-extraction.** Splitting into so many one-line functions that flow is lost. Extract for clarity, not dogma.86- **Premature abstraction.** Don't DRY up two things that merely *look* similar; wait for the third real duplication and confirm they change together.87- **Not running tests between steps.** When something breaks you won't know which step did it.8889## Bundled resources9091- `references/code-smells.md` — catalog of smells with detection signals and the refactoring each implies.92- `references/refactoring-catalog.md` — numbered, step-by-step mechanics for each core refactoring, with before/after examples.93- `references/characterization-tests.md` — how to pin legacy behavior before refactoring untested code.94- `scripts/refactor_check.sh` — verification helper: runs tests + lint/type-check and snapshots exported symbols to detect accidental API changes.95- `examples/extract-function-walkthrough.md` — a full worked example from smelly code to clean, step by step.
JayRHa