refactor

Use during REFACTOR phase of TDD or when code duplication is suspected. Defines search-first workflow and safe refactoring practices.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for the Refactor phase of the Test-Driven Development (TDD) cycle. It guides developers through a search-first workflow to identify code duplication, evaluate appropriate abstraction strategies, and implement safe code improvements. By emphasizing a 'refactor-first' mindset and providing clear safety rules, it helps engineering teams maintain high code quality, reduce technical debt, and ensure system stability through incremental, test-verified changes.

Use Cases

  • Eliminating Code Duplication: Use the search-first workflow to identify and unify redundant logic or patterns across a large codebase.
  • TDD Cycle Optimization: Systematically transition from the 'Green' phase to the 'Refactor' phase to improve code structure without altering external behavior.
  • Safe Legacy Code Modernization: Apply incremental refactoring techniques and safety rules to update existing codebases while minimizing the risk of regressions.
  • Abstraction Decision Making: Evaluate whether to extract functions, introduce interfaces, or intentionally keep duplication based on the 'rule of three' and coupling analysis.
  • Pre-Feature Preparation: Refactor existing patterns to accommodate new functionality before implementation, ensuring the codebase remains clean and extensible.
namerefactor
descriptionUse during REFACTOR phase of TDD or when code duplication is suspected. Defines search-first workflow and safe refactoring practices.

Refactor Skill

This skill provides detailed guidance for the REFACTOR phase of the RED-GREEN-REFACTOR cycle in Test-Driven Development.

When to use this skill:

  • After tests pass (GREEN phase complete)
  • When code duplication is identified
  • Before implementing new features that may duplicate existing patterns
  • During code reviews to improve code quality

Core Principle: Refactor-First Mindset

Before writing new code, always ask:

  1. Does similar functionality already exist?
  2. Can I refactor existing code to handle both cases?
  3. What patterns or abstractions are already in use?
  4. Would this be better as a modification to existing code?

Refactoring Workflow

Phase 1: Search for Existing Patterns

CRITICAL: Always search before implementing new functionality

Use code search tools to find:

  • Similar function names or patterns
  • Duplicate logic or algorithms
  • Existing abstractions that could be extended
  • Related utilities or helpers

Search strategies:

  • Grep for similar function/method names
  • Search for similar algorithm patterns
  • Look for related types or interfaces
  • Check for existing error handling patterns
  • Search for similar data transformations

Phase 2: Analyze Duplication

When similar code is found, evaluate:

Questions to ask:

  • Is this duplication intentional or accidental?
  • Do these implementations handle the same concept?
  • Can they be unified without increasing complexity?
  • Is there a common abstraction that emerges?

Red flags for duplication:

  • Copy-pasted code with minor variations
  • Similar logic in different locations
  • Repeated error handling patterns
  • Multiple implementations of same algorithm
  • Similar data validation or transformation logic

Phase 3: Choose Refactoring Strategy

Based on the duplication analysis, choose appropriate strategy:

1. Extract Function/Method

  • When: Same code block appears multiple times
  • Action: Extract to shared function
  • Benefit: Single source of truth

2. Parameterize Function

  • When: Similar functions with minor variations
  • Action: Add parameters to handle variations
  • Benefit: Reduces function count

3. Extract Common Interface/Trait

  • When: Multiple types share similar behavior
  • Action: Define shared interface
  • Benefit: Polymorphic usage

4. Introduce Abstraction Layer

  • When: Complex logic duplicated across features
  • Action: Create abstraction that handles complexity
  • Benefit: Simpler calling code

5. Use Existing Abstraction

  • When: Functionality fits existing abstraction
  • Action: Extend or modify existing abstraction
  • Benefit: Consistency with codebase patterns

6. Keep Duplication

  • When: Concepts are fundamentally different despite similar code
  • When: Unification would increase coupling inappropriately
  • When: Code will diverge in future
  • Action: Document why duplication is intentional
  • Benefit: Avoids premature abstraction

Phase 4: Refactor Safely

Safety rules for refactoring:

  1. All tests must be GREEN before starting

    • Never refactor with failing tests
    • Tests are your safety net
  2. Make small, incremental changes

    • One refactoring at a time
    • Run tests after each change
    • Commit frequently
  3. Run ALL tests after each change

    • Ensures no regression
    • Catches unintended side effects
    • Maintains confidence
  4. If tests fail, revert immediately

    • Don't try to fix forward
    • Revert and try different approach
    • Smaller steps if needed
  5. Keep refactoring separate from feature work

    • Don't mix refactoring and new features in same commit
    • Refactoring commits should not change behavior
    • Feature commits add new behavior

Phase 5: Verify and Document

After refactoring:

Verification checklist:

  • All tests still pass
  • No new compiler warnings
  • Code is more readable
  • Duplication is reduced or eliminated
  • Performance is not degraded
  • Documentation is updated

Documentation:

  • Update function/module documentation
  • Add comments explaining complex refactorings
  • Document design decisions (especially if keeping duplication)
  • Update architecture diagrams if needed

Refactoring Anti-Patterns

❌ Anti-Pattern 1: Premature Abstraction

Problem: Creating abstractions before understanding the pattern Solution: Follow "rule of three" - wait until duplication appears 3 times

❌ Anti-Pattern 2: Over-Engineering

Problem: Creating overly complex abstractions for simple duplication Solution: Keep refactoring simple and focused

❌ Anti-Pattern 3: Breaking Encapsulation

Problem: Exposing internals to reduce duplication Solution: Sometimes duplication is better than bad coupling

❌ Anti-Pattern 4: Big Bang Refactoring

Problem: Changing too much at once Solution: Small, incremental changes with test verification

❌ Anti-Pattern 5: Refactoring Without Tests

Problem: Changing code without safety net Solution: Write tests first if they don't exist

When NOT to Refactor

Skip refactoring when:

  • Tests are not passing (fix tests first)
  • Code will be deleted soon
  • Time pressure is extreme (but add TODO)
  • Concepts are fundamentally different despite similar code
  • System is stable and working (if it ain't broke...)
  • Refactoring would introduce inappropriate coupling

Integration with TDD Workflow

Refactoring is Step 4 in the RED-GREEN-REFACTOR cycle:

  1. RED: Write test that fails
  2. GREEN: Write minimal code to pass
  3. VERIFY: Run all tests
  4. REFACTOR: Improve code quality ← (this skill)
  5. VERIFY: Run all tests again
  6. REPEAT: Next test

When implementing new features:

  1. Search for existing similar patterns (use this skill)
  2. Decide: refactor existing vs. create new
  3. If refactoring: do it before adding new feature
  4. Then proceed with TDD cycle for new feature

File Organization

For guidance on splitting large files into modules: See FILE-ORGANIZATION.md for guidelines on when and how to split files.

Practical Checklist

Before writing new code:

  • Search codebase for similar functionality
  • Review existing abstractions in the area
  • Check if existing code can be extended
  • Consider refactoring existing code first
  • Document decision (refactor vs. new code)

During refactoring:

  • All tests passing before starting
  • Make one small change at a time
  • Run all tests after each change
  • Commit working changes frequently
  • Revert if tests fail

After refactoring:

  • All tests still passing
  • Code is more maintainable
  • Duplication reduced or eliminated
  • Documentation updated
  • No performance regression