Refactor (Behavior-Preserving)
Goal
Improve internal structure without changing observable behavior.
Observable behavior includes outputs, side effects, performance envelopes, error shapes, logging/metrics contracts, and public API compatibility.
Guardrails
- Preserve semantics first; readability second.
- Keep changes small and mechanical; verify after each step.
- Do not mix refactors with feature changes in the same diff.
- Prefer compiler/typechecker + tests as the safety net.
If the code has no tests, start by adding characterization tests around the current behavior (including edge cases and error paths).
Workflow
- Establish a baseline.
- Run existing tests and record what passes/fails. - Capture key behaviors with a quick harness if tests are missing. - Make a checkpoint commit before refactoring.
- Pick a single refactor target.
- Choose the smallest change that reduces future risk. - State the intent in one sentence (example: "Extract parsing from IO to enable unit tests").
- Refactor in tight loops.
- Apply one operation (rename, extract, inline, move). - Re-run the relevant tests or checks. - Repeat until the target improvement is achieved.
- Confirm "no behavior change".
- All tests pass. - No unintended public API changes. - No new side effects or missing side effects.
- Clean up.
- Remove dead code introduced by the move. - Update comments that describe outdated structure. - Leave a small, reviewable diff.
Common Moves
- Rename for intent (types, functions, variables).
- Extract function/method to reduce nesting and isolate responsibilities.
- Inline trivial wrappers that add indirection without value.
- Introduce parameter object when argument lists grow.
- Replace nested conditionals with guard clauses.
- Extract shared logic to eliminate duplication.
- Split large modules by responsibility and boundary.
References (Load As Needed)
refactor/references/checklists.md: safe workflow, review checklist, and "no tests" strategy.refactor/references/recipes.md: code smells mapped to refactor recipes with small examples.refactor/references/operations.md: quick list of common refactoring operations.refactor/references/patterns.md: type-safety refactors and when to use design patterns during a refactor.