# Refactor

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

- Skill: `majiayu000/refactor-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/refactor-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/refactor-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/refactor-2

---


# 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](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