Refactoring

Refactoring

Intro

Refactoring is changing the structure of code without changing its observable behavior. Do it in small, test-protected steps, one transformation at a time, and never mix it with feature changes in the same commit.

Overview

Verify the safety net first

Before any refactoring, run the existing tests and confirm they pass. If no tests cover the code you are about to change, write characterization tests first — tests that capture current behavior, not desired behavior. Plan the refactoring as a sequence of atomic transformations where each step keeps the suite green, and commit after each step. The golden rule: never mix refactoring with feature changes in the same commit.

Identify code smells

Scan systematically for the well-known smells. The full catalog lives in references/code-smells.md; the most common offenders:

Apply Fowler's refactoring catalog

Match smells to specific refactorings:

• Composing methods — Extract Function, Inline Function, Extract Variable, Replace Temp with Query.
• Moving features — Move Function/Field, Extract Class, Inline Class.
• Simplifying conditionals — Replace Nested Conditional with Guard Clauses, Decompose Conditional, Replace Conditional with Polymorphism, Introduce Null Object.
• Organizing data — Introduce Parameter Object, Replace Magic Number with Constant, Encapsulate Collection.
• Generalization — Pull Up / Push Down Method, Extract Interface/Trait, Replace Inheritance with Composition.

Apply GoF patterns when they simplify

Only introduce a design pattern when it solves a concrete problem, never speculatively. The full catalog is in references/gof-patterns.md. Most commonly useful: Strategy, Observer, Factory Method, Builder, Adapter, Decorator, Command, State, Template Method, Iterator. Warning signs of overuse: adding a pattern "just in case", pattern adds more code than it removes, only one implementation exists, the team cannot explain why.

Example

User says "this function is too long". The agent identifies three distinct responsibilities, extracts each into a named helper keeping the original as a high-level orchestrator, runs tests after each extraction, and commits each extraction separately.

Gotchas

Agent-specific failure modes — provider-neutral pause-and-self-check items:

• Mixing refactoring with feature changes in the same commit. When a commit changes both structure and behavior, reviewers cannot verify that behavior was preserved, and rollback becomes surgical. Keep refactoring commits separate; the commit message should start with refactor:.
• Starting without a test safety net. If the code has no tests, changing its structure with no verification is guessing. Write characterization tests first — tests that capture current behavior, not desired behavior — then refactor.
• Big-bang rewrite instead of incremental transformation. Full rewrites take longer, introduce more bugs, and stall new features during the rewrite. Refactor incrementally: one smell, one transformation, one commit, tests green throughout.
• Removing code assumed to be dead without verifying. Dynamic dispatch, reflection, plugin systems, and config-driven loads can call code that static analysis says is unreachable. Search for all invocation paths before deleting anything.
• Speculative generality. Adding extension points, plugin hooks, or configuration flags "just in case" is not refactoring — it is adding untested code for hypothetical future requirements. Refactor to the current need, not the imagined future.
• Pattern cargo-culting. Introducing a design pattern because it sounds clever adds indirection and complexity without value. Apply a pattern only when it solves a concrete, present problem — and only after the "rule of three" (three similar occurrences) is met.
• Skipping the refactor step after green. The refactor step is where the design payoff from TDD-style cycles lives. Skipping it means the test suite is green but the technical debt is accumulating.

Full reference

Modern considerations

For async/concurrent code, extract async boundaries clearly (sync core, async shell), replace callback chains with async/await where possible, and isolate side effects at the edges. For functional-style code, replace mutable loops with map/filter/reduce pipelines, extract pure functions from impure ones, and use algebraic types (enums/unions) over class hierarchies for closed sets.

Smell-to-pattern map

Selecting a pattern (rule of three)

Wait until you see a need in three places before abstracting. One occurrence is a fact, two is a coincidence, three is a pattern. Premature abstraction is harder to undo than late abstraction because the wrong shape constrains future changes.

Anti-patterns

• Mixing refactoring with feature work in the same commit
• Refactoring without a test safety net
• Speculative generality — adding hooks "just in case"
• Pattern cargo-culting — applying GoF because it sounds clever
• Big-bang rewrites instead of incremental transformation
• Removing dead code without checking it is truly unreachable (search for dynamic dispatch, reflection, config-driven loads)

Example: extracting test seams

To make code more testable, identify concrete dependencies (file I/O, HTTP, database), extract interfaces/traits at those boundaries (Adapter pattern), move domain logic into pure functions, and introduce dependency injection so tests can supply fakes. This is refactoring in service of testability, not feature work, and should ship in its own commit series.