Refactoring

Refactoring Skill

Restructure code safely while preserving behavior.

Workflow

1. Verify Test Coverage

Before refactoring, ensure tests exist:

# Run existing tests
npm test
pytest
go test ./...

If no tests cover the code:

1. Write characterization tests first
2. These capture current behavior (even if buggy)
3. Then refactor with confidence

2. Understand Current Structure

Map the code:

• What are the dependencies?
• Who calls this code?
• What does it depend on?
• What's the data flow?

# Find usages
grep -r "functionName" --include="*.ts"

# Find dependencies
grep -r "import.*from.*module" --include="*.ts"

3. Plan the Refactoring

Identify the target state:

• What's the problem with current code?
• What's the desired structure?
• What's the smallest step toward that?

Choose your approach:

| Situation | Approach | |-----------|----------| | Large function | Extract methods | | Duplicated code | Extract shared function | | Complex conditionals | Replace with polymorphism | | Long parameter list | Introduce parameter object | | Feature envy | Move method to data's class | | Data clump | Extract class |

4. Execute in Small Steps

The safe refactoring cycle:

1. Make ONE small change
2. Run tests
3. Commit if green
4. Repeat

Never skip steps:

• Don't combine multiple refactorings
• Don't "fix bugs" while refactoring
• Don't add features while refactoring

5. Verify Behavior Preserved

# Run full test suite
npm test

# Check for regressions
npm run test:e2e

# Manual smoke test if needed

Quick Reference

Safe Refactorings (Automated)

Most IDEs can do these automatically:

| Refactoring | Shortcut (VS Code) | |-------------|-------------------| | Rename | F2 | | Extract function | Ctrl+Shift+R | | Extract variable | Ctrl+Shift+R | | Inline variable | Ctrl+Shift+R | | Move to file | Drag in explorer |

Common Patterns

Extract Function

// Before
function processOrder(order) {
  // validate
  if (!order.items.length) throw new Error('Empty order');
  if (!order.customer) throw new Error('No customer');

  // calculate total
  let total = 0;
  for (const item of order.items) {
    total += item.price * item.quantity;
  }

  // apply discount
  if (order.coupon) {
    total *= (1 - order.coupon.discount);
  }

  return { ...order, total };
}

// After
function processOrder(order) {
  validateOrder(order);
  const total = calculateTotal(order);
  return { ...order, total };
}

function validateOrder(order) {
  if (!order.items.length) throw new Error('Empty order');
  if (!order.customer) throw new Error('No customer');
}

function calculateTotal(order) {
  const subtotal = order.items.reduce(
    (sum, item) => sum + item.price * item.quantity,
    0
  );
  return order.coupon
    ? subtotal * (1 - order.coupon.discount)
    : subtotal;
}

Replace Conditional with Polymorphism

// Before
function getSpeed(vehicle) {
  switch (vehicle.type) {
    case 'car': return vehicle.horsepower * 0.5;
    case 'bike': return vehicle.gears * 5;
    case 'boat': return vehicle.engineSize * 2;
  }
}

// After
class Car {
  getSpeed() { return this.horsepower * 0.5; }
}
class Bike {
  getSpeed() { return this.gears * 5; }
}
class Boat {
  getSpeed() { return this.engineSize * 2; }
}

Introduce Parameter Object

// Before
function createUser(name, email, age, country, role) {
  // ...
}

// After
function createUser({ name, email, age, country, role }) {
  // ...
}

// Or with type
interface CreateUserParams {
  name: string;
  email: string;
  age: number;
  country: string;
  role: string;
}

function createUser(params: CreateUserParams) {
  // ...
}

Code Smells to Address

| Smell | Refactoring | |-------|-------------| | Long method | Extract method | | Large class | Extract class | | Duplicate code | Extract function | | Long parameter list | Parameter object | | Switch statements | Polymorphism | | Feature envy | Move method | | Data clump | Extract class | | Primitive obsession | Value object | | Comments explaining code | Extract well-named method |

Anti-Patterns

Don't:

1. Refactor and change behavior simultaneously

• Refactoring = same behavior, different structure
• Keep them separate

1. Make big-bang changes

• Small steps with tests passing between each

1. Refactor without tests

• Write characterization tests first

1. Over-abstract too early

• Wait for duplication to appear 3 times

1. Refactor "just in case"

• Refactor for a reason (readability, extensibility needed now)

See Also

• [patterns.md](./patterns.md) - Detailed refactoring patterns with examples

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AvinashP
• Source: AvinashP/AgentsAtlas
• License: MIT

Install and usage instructions live in the source repository linked above.