refactor

Code Refactoring Skill

A systematic approach to refactoring code based on Martin Fowler's Refactoring: Improving the Design of Existing Code (2nd Edition). This skill emphasizes safe, incremental changes backed by tests.

"Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code yet improves its internal structure." — Martin Fowler

Core Principles

1. Behavior Preservation: External behavior must remain unchanged
2. Small Steps: Make tiny, testable changes
3. Test-Driven: Tests are the safety net
4. Continuous: Refactoring is ongoing, not a one-time event
5. Collaborative: User approval required at each phase

Workflow Overview

Phase 1: Research & Analysis
    ↓
Phase 2: Test Coverage Assessment
    ↓
Phase 3: Code Smell Identification
    ↓
Phase 4: Refactoring Plan Creation
    ↓
Phase 5: Incremental Implementation
    ↓
Phase 6: Review & Iteration

Phase 1: Research & Analysis

Objectives

• Understand the codebase structure and purpose
• Identify the scope of refactoring
• Gather context about business requirements

Questions to Ask User

Before starting, clarify:

1. Scope: Which files/modules/functions need refactoring?
2. Goals: What problems are you trying to solve? (readability, performance, maintainability)
3. Constraints: Are there any areas that should NOT be changed?
4. Timeline pressure: Is this blocking other work?
5. Test status: Do tests exist? Are they passing?

Actions

• Read and understand the target code
• Identify dependencies and integrations
• Document current architecture
• Note any existing technical debt markers (TODOs, FIXMEs)

Output

Present findings to user:

• Code structure summary
• Identified problem areas
• Initial recommendations
• Request approval to proceed

Phase 2: Test Coverage Assessment

Why Tests Matter

"Refactoring without tests is like driving without a seatbelt." — Martin Fowler

Tests are the key enabler of safe refactoring. Without them, you risk introducing bugs.

Assessment Steps

1. Check for existing tests

   # Look for test files
   find . -name "*test*" -o -name "*spec*" | head -20
   

2. Run existing tests

   # JavaScript/TypeScript
   npm test
   
   # Python
   pytest -v
   
   # Java
   mvn test
   

3. Check coverage (if available)

   # JavaScript
   npm run test:coverage
   
   # Python
   pytest --cov=.
   

Decision Point: Ask User

If tests exist and pass:

• Proceed to Phase 3

If tests are missing or incomplete: Present options:

1. Write tests first (recommended)
2. Add tests incrementally during refactoring
3. Proceed without tests (risky - requires user acknowledgment)

If tests are failing:

• STOP. Fix failing tests before refactoring
• Ask user: Should we fix tests first?

Test Writing Guidelines (if needed)

For each function being refactored, ensure tests cover:

• Happy path (normal operation)
• Edge cases (empty inputs, null, boundaries)
• Error scenarios (invalid inputs, exceptions)

Use the "red-green-refactor" cycle:

1. Write failing test (red)
2. Make it pass (green)
3. Refactor

Phase 3: Code Smell Identification

What Are Code Smells?

Symptoms of deeper problems in code. They're not bugs, but indicators that the code could be improved.

Common Code Smells to Check

See references/code-smells.md for the complete catalog.

Quick Reference

Analysis Steps

1. Automated Analysis (if scripts available)

   python scripts/detect-smells.py <file>
   

2. Manual Review

   • Walk through code systematically
   • Note each smell with location and severity
   • Categorize by impact (Critical/High/Medium/Low)

3. Prioritization Focus on smells that:

   • Block current development
   • Cause bugs or confusion
   • Affect most-changed code paths

Output: Smell Report

Present to user:

• List of identified smells with locations
• Severity assessment for each
• Recommended priority order
• Request approval on priorities

Phase 4: Refactoring Plan Creation

Selecting Refactorings

For each smell, select an appropriate refactoring from the catalog.

See references/refactoring-catalog.md for the complete list.

Smell-to-Refactoring Mapping

Plan Structure

Use the template at templates/refactoring-plan.md.

For each refactoring:

1. Target: What code will change
2. Smell: What problem it addresses
3. Refactoring: Which technique to apply
4. Steps: Detailed micro-steps
5. Risks: What could go wrong
6. Rollback: How to undo if needed

Phased Approach

CRITICAL: Introduce refactoring gradually in phases.

Phase A: Quick Wins (Low risk, high value)

• Rename variables for clarity
• Extract obvious duplicate code
• Remove dead code

Phase B: Structural Improvements (Medium risk)

• Extract methods from long functions
• Introduce parameter objects
• Move methods to appropriate classes

Phase C: Architectural Changes (Higher risk)

• Replace conditionals with polymorphism
• Extract classes
• Introduce design patterns

Decision Point: Present Plan to User

Before implementation:

• Show complete refactoring plan
• Explain each phase and its risks
• Get explicit approval for each phase
• Ask: "Should I proceed with Phase A?"

Phase 5: Incremental Implementation

The Golden Rule

"Change → Test → Green? → Commit → Next step"

Implementation Rhythm

For each refactoring step:

1. Pre-check

   • Tests are passing (green)
   • Code compiles

2. Make ONE small change

   • Follow the mechanics from the catalog
   • Keep changes minimal

3. Verify

   • Run tests immediately
   • Check for compilation errors

4. If tests pass (green)

   • Commit with descriptive message
   • Move to next step

5. If tests fail (red)

   • STOP immediately
   • Undo the change
   • Analyze what went wrong
   • Ask user if unclear

Commit Strategy

Each commit should be:

• Atomic: One logical change
• Reversible: Easy to revert
• Descriptive: Clear commit message

Example commit messages:

refactor: Extract calculateTotal() from processOrder()
refactor: Rename 'x' to 'customerCount' for clarity
refactor: Remove unused validateOldFormat() method

Progress Reporting

After each sub-phase, report to user:

• Changes made
• Tests still passing?
• Any issues encountered
• Ask: "Continue with next batch?"

Phase 6: Review & Iteration

Post-Refactoring Checklist

• All tests passing
• No new warnings/errors
• Code compiles successfully
• Behavior unchanged (manual verification)
• Documentation updated if needed
• Commit history is clean

Metrics Comparison

Run complexity analysis before and after:

python scripts/analyze-complexity.py <file>

Present improvements:

• Lines of code change
• Cyclomatic complexity change
• Maintainability index change

User Review

Present final results:

• Summary of all changes
• Before/after code comparison
• Metrics improvements
• Remaining technical debt
• Ask: "Are you satisfied with these changes?"

Next Steps

Discuss with user:

• Additional smells to address?
• Schedule follow-up refactoring?
• Apply similar changes elsewhere?

Important Guidelines

When to STOP and Ask

Always pause and consult user when:

• Unsure about business logic
• Change might affect external APIs
• Test coverage is inadequate
• Significant architectural decision needed
• Risk level increases
• You encounter unexpected complexity

Safety Rules

1. Never refactor without tests (unless user explicitly acknowledges risk)
2. Never make big changes - break into tiny steps
3. Never skip the test run after each change
4. Never continue if tests fail - fix or rollback first
5. Never assume - when in doubt, ask

What NOT to Do

• Don't combine refactoring with feature additions
• Don't refactor during production emergencies
• Don't refactor code you don't understand
• Don't over-engineer - keep it simple
• Don't refactor everything at once

Quick Start Example

Scenario: Long Method with Duplication

Before:

function processOrder(order) {
  // 150 lines of code with:
  // - Duplicated validation logic
  // - Inline calculations
  // - Mixed responsibilities
}

Refactoring Steps:

1. Ensure tests exist for processOrder()
2. Extract validation into validateOrder()
3. Test - should pass
4. Extract calculation into calculateOrderTotal()
5. Test - should pass
6. Extract notification into notifyCustomer()
7. Test - should pass
8. Review - processOrder() now orchestrates 3 clear functions

After:

function processOrder(order) {
  validateOrder(order);
  const total = calculateOrderTotal(order);
  notifyCustomer(order, total);
  return { order, total };
}

References

• Code Smells Catalog - Complete list of code smells
• Refactoring Catalog - Refactoring techniques
• Refactoring Plan Template - Planning template

Scripts

• scripts/analyze-complexity.py - Analyze code complexity metrics
• scripts/detect-smells.py - Automated smell detection

Version History

• v1.0.0 (2025-01-15): Initial release with Fowler methodology, phased approach, user consultation points

Last Updated: August 4, 2026 Claude Code Version: 2.1.220 Sources:

• https://code.claude.com/docs/en/skills Compatible Models: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5