refactor-expert
Guide safe, incremental refactoring that improves code quality without changing behavior.
When & Why to Use This Skill
Refactor Expert is a specialized Claude skill designed to facilitate safe, incremental code refactoring and technical debt reduction. It empowers developers to improve code maintainability, readability, and structure without altering external behavior. By identifying common code smells and applying industry-standard design patterns, this tool ensures a cleaner, more robust codebase through structured analysis and systematic implementation plans.
Use Cases
- Technical Debt Reduction: Automatically identify and resolve code smells such as Long Methods, Large Classes, and Duplicate Code to improve long-term project health.
- Logic Simplification: Transform complex, nested conditional statements into clean, readable code using patterns like 'Replace Conditional with Polymorphism' or 'Simplify Conditional'.
- Safe Structural Changes: Generate comprehensive refactoring analysis and implementation plans to ensure changes are made incrementally and verified by existing test suites.
- Code Quality Standardization: Assist teams in breaking down monolithic functions into smaller, testable, and reusable methods to align with 'Clean Code' principles.
- Architectural Evolution: Guide the transition from primitive-heavy code to object-oriented structures, enhancing the overall software design and extensibility.
| name | refactor-expert |
|---|---|
| description | "Guide safe, incremental refactoring that improves code quality without changing behavior." |
| autoInvoke | false |
| priority | medium |
| - "refactor | plan" |
Skill: Refactor Expert
Category: Dev Expert Version: 1.1.0 Used By: All development agents
Overview
Guide safe, incremental refactoring that improves code quality without changing behavior.
Documentation Commands
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
1. Refactoring Decision
| 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.
2. Common Refactoring Patterns
Extract Method
// 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)
}
Replace Conditional with Polymorphism
// 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 } }
Simplify Conditional
// 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)
3. Code Smells → Refactoring
| 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 |
4. Safe Refactoring Steps
1. Ensure tests pass ✅
2. Make ONE small change
3. Run tests ✅
4. Commit
5. Repeat
Never: Multiple changes between test runs.
5. Refactoring Checklist
Before:
- Tests exist and pass
- Understand current behavior
- Identify specific smell
During:
- One change at a time
- Tests after each change
- Commit frequently
After:
- All tests pass
- Code cleaner
- Behavior unchanged
Best Practices
Do's
- Test first, refactor second
- Small, incremental changes
- Commit after each successful refactor
- Use IDE refactoring tools
- Document why (not what)
Don'ts
- Refactor without tests
- Mix refactoring with features
- Make large changes at once
- Refactor code you don't understand
- Over-refactor working code
Related Commands
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-focused
Version: 1.1.0 | Last Updated: 2025-12-04