Refactoring Patterns

Catalog of safe, incremental code transformation patterns.

When to Invoke

• Executing /refactor command
• Technical debt remediation
• Pattern migration (e.g., callbacks → async/await)
• Code smell resolution from static analysis findings

Code Smell Taxonomy

Structural Smells

Smell	Detection	Refactoring
Long method	>30 lines	Extract method
Large class	>300 lines or >5 responsibilities	Extract class
Long parameter list	>4 parameters	Introduce parameter object
Feature envy	Method uses another class's data more than its own	Move method
Data clumps	Same fields appear together repeatedly	Extract class
Primitive obsession	Primitives where domain types belong	Introduce value object

Coupling Smells

Smell	Detection	Refactoring
God class	One class knows/does too much	Extract classes by responsibility
Circular dependency	A → B → A	Introduce interface, dependency inversion
Inappropriate intimacy	Classes access each other's internals	Move method, extract interface
Shotgun surgery	One change requires touching many files	Move related code together

Safe Transformation Techniques

1. Characterization Tests

Before refactoring, write tests that capture current behavior:

Run existing code → record outputs → assert in tests → now refactor safely

2. Strangler Fig Pattern

Gradually replace old implementation with new:

Old Code ← requests
         ↓ gradually route to
New Code ← requests (eventually all traffic)
Old Code ← delete

3. Branch by Abstraction

1. Create abstraction (interface) over existing implementation
2. Modify all clients to use abstraction
3. Create new implementation behind abstraction
4. Switch to new implementation
5. Remove old implementation

4. Parallel Run

Run old and new implementations simultaneously, compare outputs:

Request → Old Implementation → Response (returned to user)
       → New Implementation → Response (logged, compared)

Behavior Preservation Checklist

• Tests pass before starting
• Each step is a single, atomic change
• Tests pass after each step
• Same inputs produce same outputs
• Coverage ≥ pre-refactoring level
• No new public API surface (unless intentional)
• Complexity metrics improved or unchanged

Metrics

Metric	Tool	Target
Cyclomatic complexity	SonarQube, radon, gocyclo	≤ 10 per function
Cognitive complexity	SonarQube	≤ 15 per function
Coupling (afferent/efferent)	JDepend, NDepend	Decreasing trend
Duplication	SonarQube, jscpd	< 3%
Test coverage	lcov, coverage.py	≥ pre-refactoring

Related

• Code Review @.agents/skills/code-review/SKILL.md
• Guardrails @.agents/skills/guardrails/SKILL.md
• Testing Strategy .agents/rules/testing-strategy.md