Safely Modernizing Legacy Code with Claude Code

How to Tackle Legacy Code

No tests, outdated docs, and code nobody wants to touch. Claude Code is a powerful ally for understanding and improving legacy code like this.

Step 1: Understanding the Code

Start by having Claude Code analyze the code.

> Analyze the code under src/legacy/.
> Explain the responsibilities, dependencies, and data flow of each file.
> Also suggest problem areas and improvement priorities.

Claude Code reads through the entire codebase and presents a structural explanation and improvement plan.

Step 2: Adding Tests

Before making any changes, write tests to lock down the current behavior.

> Create tests that guarantee the current behavior of
> src/legacy/orderProcessor.js.
> Analyze the function's inputs and outputs, covering both
> success and error cases.
> Don't modify the code yet.

// Tests to guarantee existing behavior of legacy code
import { processOrder } from "../legacy/orderProcessor";

describe("processOrder - guaranteeing existing behavior", () => {
  it("processes a valid order", () => {
    const order = {
      items: [{ id: "A1", qty: 2, price: 1000 }],
      customer: { id: "C1", type: "regular" },
    };
    const result = processOrder(order);
    expect(result.total).toBe(2000);
    expect(result.status).toBe("confirmed");
  });

  it("returns error for an empty order", () => {
    const order = { items: [], customer: { id: "C1", type: "regular" } };
    const result = processOrder(order);
    expect(result.status).toBe("error");
    expect(result.message).toContain("items");
  });

  it("applies discount for VIP customers", () => {
    const order = {
      items: [{ id: "A1", qty: 1, price: 10000 }],
      customer: { id: "C2", type: "vip" },
    };
    const result = processOrder(order);
    expect(result.total).toBe(9000); // 10% off
  });
});

Step 3: Incremental Refactoring

Improve gradually while ensuring tests continue to pass.

> Refactor orderProcessor.js while keeping tests green:
> 1. Convert to TypeScript
> 2. Add type definitions
> 3. Split into single-responsibility functions
> 4. Verify tests pass after each change

// Structure after refactoring
// orderProcessor.ts - main processing
export function processOrder(order: OrderInput): OrderResult {
  const validation = validateOrder(order);
  if (!validation.valid) {
    return { status: "error", message: validation.message };
  }

  const subtotal = calculateSubtotal(order.items);
  const discount = calculateDiscount(subtotal, order.customer);
  const total = subtotal - discount;

  return {
    status: "confirmed",
    total,
    items: order.items,
    discount,
  };
}

// validators.ts - validation
export function validateOrder(order: OrderInput): ValidationResult {
  if (!order.items || order.items.length === 0) {
    return { valid: false, message: "items is required" };
  }
  return { valid: true };
}

// calculators.ts - calculation logic
export function calculateSubtotal(items: OrderItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.qty, 0);
}

export function calculateDiscount(subtotal: number, customer: Customer): number {
  if (customer.type === "vip") {
    return subtotal * 0.1;
  }
  return 0;
}

Step 4: Migrating from JavaScript to TypeScript

> Convert all JS files under src/legacy/ to TypeScript.
> 1. Rename .js to .ts
> 2. Get type checking to pass with any types first
> 3. Replace any with proper types
> 4. Verify tests pass after each step

Eliminating Callback Hell

> Rewrite callback-based async processing
> to async/await.

// Before fix: callback hell
function fetchUserData(userId, callback) {
  db.getUser(userId, (err, user) => {
    if (err) return callback(err);
    db.getPosts(user.id, (err, posts) => {
      if (err) return callback(err);
      db.getComments(posts[0].id, (err, comments) => {
        if (err) return callback(err);
        callback(null, { user, posts, comments });
      });
    });
  });
}

// After fix: async/await
async function fetchUserData(userId: string): Promise<UserData> {
  const user = await db.getUser(userId);
  const posts = await db.getPosts(user.id);
  const comments = posts.length > 0
    ? await db.getComments(posts[0].id)
    : [];
  return { user, posts, comments };
}

Updating Dependencies

> Identify outdated dependencies in package.json.
> List any that are 2+ major versions behind.
> Also investigate breaking changes for updates.

For specific refactoring patterns, see the Refactoring Automation Guide. For test-addition strategies, see TDD and Claude Code. For updating documentation during incremental improvements, also check out Documentation Auto-Generation.

Summary

The key to improving legacy code is “build a safety net with tests, then change incrementally.” Claude Code dramatically streamlines this process. Don’t try to change everything at once — take it step by step.

The philosophy behind the classic book Working Effectively with Legacy Code pairs extremely well with Claude Code. For Claude Code details, see the official Anthropic documentation.