Guide safe, incremental refactoring that improves code quality without changing behavior.
Category: Dev Expert Version: 1.1.0 Used By: All development agents
Guide safe, incremental refactoring that improves code quality without changing behavior.
Generate analysis and implementation plans before refactoring:
| Command | Purpose | Output |
|---|---|---|
refactor:analyze <file> | Code analysis document | .claude/logs/refactors/{target}-analysis.md |
refactor:plan <file> | Implementation plan | .claude/logs/refactors/{target}-plan.md |
refactor:docs <file> | Both documents | Analysis + Plan + Summary |
Templates: templates/refactor-analysis.md, templates/refactor-plan.md
| Signal | Action |
|---|---|
| Code smell detected | Identify specific smell |
| Tests passing | Safe to refactor |
| No tests | Write tests FIRST |
| Large change needed | Break into small steps |
Golden Rule: Never refactor and add features simultaneously.
// Before
function processOrder(order: Order) {
// validate
if (!order.items.length) throw new Error('Empty')
if (!order.customer) throw new Error('No customer')
// calculate
let total = 0
for (const item of order.items) {
total += item.price * item.qty
}
return total
}
// After
function processOrder(order: Order) {
validateOrder(order)
return calculateTotal(order.items)
}
// Before
function getPrice(type: string, base: number) {
if (type === 'premium') return base * 0.8
if (type === 'vip') return base * 0.7
return base
}
// After
interface PricingStrategy { calculate(base: number): number }
class PremiumPricing implements PricingStrategy { calculate(base: number) { return base * 0.8 } }
// Before
if (date.before(SUMMER_START) || date.after(SUMMER_END)) { charge = qty * winterRate }
else { charge = qty * summerRate }
// After
const isSummer = !date.before(SUMMER_START) && !date.after(SUMMER_END)
charge = qty * (isSummer ? summerRate : winterRate)
| Smell | Refactoring |
|---|---|
| Long Method | Extract Method |
| Large Class | Extract Class |
| Long Parameter List | Introduce Parameter Object |
| Duplicate Code | Extract Method/Class |
| Feature Envy | Move Method |
| Data Clumps | Extract Class |
| Primitive Obsession | Replace with Object |
| Switch Statements | Replace with Polymorphism |
| Speculative Generality | Remove unused abstraction |
| Dead Code | Delete it |
1. Ensure tests pass ✅
2. Make ONE small change
3. Run tests ✅
4. Commit
5. Repeat
Never: Multiple changes between test runs.
Before:
During:
After:
refactor <file> - Full refactoring workflowrefactor:analyze <file> - Analysis document onlyrefactor:plan <file> - Implementation plan onlyrefactor:docs <file> - Both documentsrefactor:quick <file> - Skip approvalsrefactor:performance <file> - Performance-focusedrefactor:structure <file> - Structure-focusedVersion: 1.1.0 | Last Updated: 2025-12-04