Refactoring Patterns

Refactoring is the discipline of restructuring existing code without changing its observable behavior. The goal is to make code easier to understand, cheaper to modify, and less likely to harbor bugs. Each refactoring move is a named, repeatable transformation - applying them in small, tested steps keeps the codebase safe. This skill gives an agent the vocabulary and judgment to recognize structural problems, choose the right refactoring move, and execute it correctly.

When to use this skill

Trigger this skill when the user:

• Asks to extract a method, function, or block into a named helper
• Has a long if/else chain or switch that grows with every new case
• Wants to simplify a function with too many parameters
• Asks to replace magic numbers or string literals with named constants
• Wants to break apart a large class that does too many things
• Has complex conditional logic that is hard to read at a glance
• Asks for "systematic" code improvement without changing behavior
• Wants to eliminate duplication across multiple files or classes

Do NOT trigger this skill for:

• Performance optimization - refactoring targets readability, not speed
• Architecture decisions that change system boundaries (use clean-architecture instead)

Key principles

1. Small steps with tests - Apply one refactoring at a time and verify tests pass after each step. A failing test means the refactoring changed behavior.

2. Preserve observable behavior - Callers must not notice the change. Return values, side effects, and thrown errors must remain identical.

3. One refactor at a time - Don't mix Extract Method with Rename Variable in one commit. Each commit should contain exactly one named refactoring move.

4. Refactor before adding features - Fowler's rule: make the change easy, then make the easy change. Restructure first, add the feature second.

5. Code smells signal refactoring need - Smells like long functions, duplicated code, and large parameter lists are symptoms pointing to the correct refactoring move. See references/code-smells.md for the full catalog.

Core concepts

Code smells taxonomy

Code smells are categories of structural problems, each suggesting specific moves:

Refactoring safety net

Never refactor without tests. If tests don't exist, write characterization tests first - tests that capture the current behavior before you change anything. The test suite is the contract that proves the refactoring preserved behavior.

Common tasks

Extract method

Apply when a function contains a section that can be given a meaningful name.

Before:

function printOrderSummary(order: Order): void {
  // print header
  console.log("=".repeat(40));
  console.log(`Order #${order.id} - ${order.customer.name}`);
  console.log(`Date: ${order.createdAt.toLocaleDateString()}`);
  console.log("=".repeat(40));

  // print line items
  for (const item of order.items) {
    const lineTotal = item.price * item.quantity;
    console.log(`  ${item.name} x${item.quantity} @ $${item.price} = $${lineTotal}`);
  }

  // print totals
  const subtotal = order.items.reduce((sum, i) => sum + i.price * i.quantity, 0);
  const tax = subtotal * 0.08;
  console.log(`Subtotal: $${subtotal.toFixed(2)}`);
  console.log(`Tax (8%): $${tax.toFixed(2)}`);
  console.log(`Total:    $${(subtotal + tax).toFixed(2)}`);
}

After:

function printOrderSummary(order: Order): void {
  printOrderHeader(order);
  printLineItems(order.items);
  printOrderTotals(order.items);
}

function printOrderHeader(order: Order): void {
  console.log("=".repeat(40));
  console.log(`Order #${order.id} - ${order.customer.name}`);
  console.log(`Date: ${order.createdAt.toLocaleDateString()}`);
  console.log("=".repeat(40));
}

function printLineItems(items: OrderItem[]): void {
  for (const item of items) {
    const lineTotal = item.price * item.quantity;
    console.log(`  ${item.name} x${item.quantity} @ $${item.price} = $${lineTotal}`);
  }
}

function printOrderTotals(items: OrderItem[]): void {
  const subtotal = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
  const tax = subtotal * 0.08;
  console.log(`Subtotal: $${subtotal.toFixed(2)}`);
  console.log(`Tax (8%): $${tax.toFixed(2)}`);
  console.log(`Total:    $${(subtotal + tax).toFixed(2)}`);
}

Replace conditional with polymorphism

Apply when a switch or if/else dispatches behavior by type, and new types keep getting added. Each new case is a modification to existing code - a violation of OCP.

Before:

function calculateShipping(order: Order): number {
  switch (order.shippingMethod) {
    case "standard": return order.weight * 0.5;
    case "express":  return order.weight * 1.5 + 5;
    case "overnight": return order.weight * 3.0 + 15;
    default: throw new Error(`Unknown shipping method: ${order.shippingMethod}`);
  }
}

After:

interface ShippingStrategy {
  calculate(order: Order): number;
}

class StandardShipping implements ShippingStrategy {
  calculate(order: Order): number { return order.weight * 0.5; }
}

class ExpressShipping implements ShippingStrategy {
  calculate(order: Order): number { return order.weight * 1.5 + 5; }
}

class OvernightShipping implements ShippingStrategy {
  calculate(order: Order): number { return order.weight * 3.0 + 15; }
}

// Adding a new method = new class only, no modification to existing code
function calculateShipping(order: Order, strategy: ShippingStrategy): number {
  return strategy.calculate(order);
}

Introduce parameter object

Apply when a function receives 4+ related parameters that travel together.

Before:

function createReport(
  title: string,
  startDate: Date,
  endDate: Date,
  authorId: string,
  format: "pdf" | "csv",
  includeCharts: boolean
): Report { ... }

After:

interface ReportOptions {
  title: string;
  dateRange: { start: Date; end: Date };
  authorId: string;
  format: "pdf" | "csv";
  includeCharts: boolean;
}

function createReport(options: ReportOptions): Report { ... }

Replace magic numbers with named constants

Apply when numeric or string literals appear in logic without explanation.

Before:

function isEligibleForDiscount(user: User): boolean {
  return user.totalPurchases > 500 && user.accountAgeDays > 90;
}

function calculateLateFee(daysLate: number): number {
  return daysLate * 2.5;
}

After:

const DISCOUNT_PURCHASE_THRESHOLD = 500;
const DISCOUNT_ACCOUNT_AGE_DAYS = 90;
const LATE_FEE_PER_DAY = 2.5;

function isEligibleForDiscount(user: User): boolean {
  return (
    user.totalPurchases > DISCOUNT_PURCHASE_THRESHOLD &&
    user.accountAgeDays > DISCOUNT_ACCOUNT_AGE_DAYS
  );
}

function calculateLateFee(daysLate: number): number {
  return daysLate * LATE_FEE_PER_DAY;
}

Decompose conditional

Apply when a complex boolean expression obscures what condition is actually being tested. Extract each clause into a named predicate.

Before:

if (
  user.subscription === "premium" &&
  user.accountAgeDays > 30 &&
  !user.isSuspended &&
  (user.region === "US" || user.region === "CA")
) {
  grantEarlyAccess(user);
}

After:

function isPremiumUser(user: User): boolean {
  return user.subscription === "premium";
}

function isEstablishedAccount(user: User): boolean {
  return user.accountAgeDays > 30 && !user.isSuspended;
}

function isEligibleRegion(user: User): boolean {
  return user.region === "US" || user.region === "CA";
}

if (isPremiumUser(user) && isEstablishedAccount(user) && isEligibleRegion(user)) {
  grantEarlyAccess(user);
}

Extract class

Apply when a class has a cluster of fields and methods that form a distinct responsibility. The test: can you describe the class in one sentence without "and"?

Before:

class User {
  id: string;
  name: string;
  email: string;
  street: string;
  city: string;
  state: string;
  zip: string;

  getFullAddress(): string {
    return `${this.street}, ${this.city}, ${this.state} ${this.zip}`;
  }

  isValidAddress(): boolean {
    return Boolean(this.street && this.city && this.state && this.zip);
  }
}

After:

class Address {
  constructor(
    public street: string,
    public city: string,
    public state: string,
    public zip: string
  ) {}

  toString(): string {
    return `${this.street}, ${this.city}, ${this.state} ${this.zip}`;
  }

  isValid(): boolean {
    return Boolean(this.street && this.city && this.state && this.zip);
  }
}

class User {
  id: string;
  name: string;
  email: string;
  address: Address;
}

Replace temp with query

Apply when a local variable stores a computed value that could be a method call. Eliminates the variable and makes the intent reusable.

Before:

function applyDiscount(order: Order): number {
  const basePrice = order.items.reduce((sum, i) => sum + i.price * i.quantity, 0);
  const discount = basePrice > 100 ? basePrice * 0.1 : 0;
  return basePrice - discount;
}

After:

function basePrice(order: Order): number {
  return order.items.reduce((sum, i) => sum + i.price * i.quantity, 0);
}

function discount(order: Order): number {
  return basePrice(order) > 100 ? basePrice(order) * 0.1 : 0;
}

function applyDiscount(order: Order): number {
  return basePrice(order) - discount(order);
}

Anti-patterns / common mistakes

Gotchas

1. Refactoring without a characterization test safety net - When tests don't exist, write characterization tests that capture current behavior before touching anything. A refactoring without a test that would catch a behavioral change is a gamble, not a refactoring.

2. Extract Method applied to code that shares mutable state - Extracting a method that reads or writes shared mutable state (class fields, closures) can introduce subtle bugs when the extracted function is called in a different order. Verify that the extracted method is free of hidden state coupling before extracting.

3. Replace Conditional with Polymorphism on a switch that never grows - The Strategy pattern adds classes, indirection, and cognitive overhead. Only apply it when new cases are expected. A switch with three stable cases is often clearer than three classes plus a factory.

4. Mixing refactoring and feature work in one commit - Combined commits make it impossible to bisect a regression to either the refactoring or the feature. Keep them separate. If you discover a needed refactoring while implementing a feature, commit the refactoring first on its own.

5. Rename refactoring done with find-and-replace instead of IDE tooling - Manual find-and-replace misses dynamic usages, string references, and cross-file cases. Always use the IDE's rename refactoring which understands symbol scope, and review the diff carefully before committing.

References

For detailed content on specific topics, read the relevant file from references/:

• references/code-smells.md - Catalog of 15+ smells with detection criteria and recommended refactoring for each

Only load the reference file when the task requires identifying a specific smell or choosing between multiple refactoring moves.