Move the database, the API, or the UI. Move the application to a new framework, runtime, cloud provider, or architecture.

That sounds reasonable, but there's a problem.

If the current system mixes business rules, persistence, infrastructure, external integrations, and orchestration inside the same modules, migration becomes much harder than it needs to be.

You're not just moving software. You're trying to move several responsibilities that have become entangled over years of development.

This is why I often prefer to refactor before migrating. Not to make the legacy system beautiful or redesign everything. And definitely not to turn the preparation phase into another rewrite.

The goal is much narrower: change the structure enough that important behavior can move independently.

In the previous steps of this workflow, we first tried to understand the codebase and then used characterization tests to protect the behavior we were about to change.

Now you'll learn how you can start changing the structure.

In this tutorial, I'll show you how to prepare a legacy application for migration by:

• choosing a migration boundary,

• separating business rules from infrastructure,

• introducing seams,

• isolating side effects,

• creating adapters around external systems,

• reducing dependency direction problems,

• extracting cohesive application behavior,

• using characterization tests throughout the refactor,

• using AI without letting it redesign the system blindly,

• and knowing when the application is ready to start migrating.

The examples use TypeScript, but the process applies to most languages and architectures.

The objective is not:

legacy application
↓
perfect architecture

Instead, it's:

legacy application
↓
migration-friendly structure
↓
incremental migration

That difference can save a lot of unnecessary work.

Prerequisites

You should be comfortable with:

• reading an existing codebase

• TypeScript or a similar language

• unit and integration testing

• dependency injection

• interfaces and adapters

• basic software architecture

• incremental refactoring

You should also have some behavioral protection around the capability you plan to modify.

That may include:

• characterization tests

• integration tests

• contract tests

or another reliable way to verify existing behavior.

Refactoring without that protection is possible. But it's also much harder to distinguish a structural improvement from an accidental behavioral change.

Table of Contents

• Prerequisites

• Why Migration Problems Often Start Before the Migration

• Choose a Migration Boundary Before Refactoring

• Don't Refactor the Entire Application

• Separate Business Rules from Infrastructure

• Introduce Seams Around Hard Dependencies

• Isolate Side Effects from Decision Logic

• Put External Systems Behind Adapters

• Improve Dependency Direction Without Rebuilding Everything

• Extract a Cohesive Application Boundary

• Keep Behavioral Tests Running During the Refactor

• How to Use AI During Structural Refactoring

• Don't Ask AI to Design the Target Architecture Too Early

• How to Know When a Capability Is Ready to Migrate

• A Practical Pre-Migration Refactoring Workflow

• What Not to Refactor Before Migration

• Refactoring Is Preparation, Not the Migration

• Conclusion

Why Migration Problems Often Start Before the Migration

Imagine you need to migrate an order-processing application.

You inspect the main service and find something like this:

async function processOrder(orderId: string) {
  const connection = await mysql.getConnection();

  const [rows] = await connection.query(
    "SELECT * FROM orders WHERE id = ?",
    [orderId]
  );

  const order = rows[0];

  if (!order) {
    throw new Error("Order not found");
  }

  if (order.customer_type === "PREMIUM") {
    order.total = order.total * 0.9;
  }

  if (
    order.country === "AR" &&
    order.payment_method === "TRANSFER"
  ) {
    order.total -= 500;
  }

  await connection.query(
    "UPDATE orders SET total = ?, status = ? WHERE id = ?",
    [order.total, "PROCESSED", order.id]
  );

  await paymentProvider.createPayment({
    orderId: order.id,
    amount: order.total,
  });

  await eventBus.publish("order.processed", {
    id: order.id,
    total: order.total,
  });

  await emailClient.send({
    to: order.customer_email,
    template: "order-processed",
  });

  return order;
}

Suppose the migration goal is:

MySQL       → PostgreSQL
Old runtime → New runtime
Legacy API  → New service

The obvious temptation is to begin translating this function into the target stack.

But what exactly are you migrating?

The function contains:

database access
business rules
state transition
payment integration
event publication
email delivery
application orchestration

Changing the database now risks affecting pricing, while changing the payment client risks affecting persistence. And moving the function into another service means moving all of its dependencies at once.

The migration difficulty is partly caused by the current structure. So before migrating, you'll want to create enough separation that those concerns can move independently.

Choose a Migration Boundary Before Refactoring

Don't begin with:

Let's clean up the application.

Begin with:

What do we want to migrate first?

Suppose you decide the first capability will be Process Order. That gives your refactor a boundary.

Now you can map:

Input:
orderId

Business behavior:
load order
calculate adjustments
mark as processed

Side effects:
persist order
create payment
publish event
send email

Output:
processed order

This is much more useful than deciding to refactor:

src/services/

because a folder isn't necessarily a business boundary.

Migration works better when you can reason about capabilities.

For example:

Process Order
Cancel Order
Generate Invoice
Register Customer
Renew Subscription

Each can potentially become a migration unit.

Don't Refactor the Entire Application

Once you start identifying architectural problems, it becomes tempting to fix all of them.

You may notice:

circular dependencies
duplicated repositories
global configuration
large services
static helpers
direct database access
inconsistent error handling
mixed domain models

All of those may deserve attention, but the migration doesn't require all technical debt to disappear.

Suppose your target is the order-processing capability. A useful rule is to refactor only what prevents this capability from moving safely.

For example:

Problem:
Order processing calls MySQL directly.

Relevant?
Yes.

Problem:
The reporting module uses inconsistent date formatting.

Relevant?
Probably not.

Problem:
Order processing calls the payment SDK directly.

Relevant?
Yes.

Problem:
The admin UI contains duplicated CSS.

Relevant?
No.

This prevents preparation from becoming an open-ended cleanup project.

Legacy modernization needs scope discipline.

Separate Business Rules from Infrastructure

The most valuable structural change is often separating business behavior from technology-specific details.

Take this code:

async function processOrder(orderId: string) {
  const order = await mysqlOrders.find(orderId);

  if (order.customerType === "PREMIUM") {
    order.total *= 0.9;
  }

  if (
    order.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    order.total -= 500;
  }

  await mysqlOrders.update(order);

  await stripe.createPayment({
    orderId: order.id,
    amount: order.total,
  });
}

The pricing behavior itself doesn't need MySQL or Stripe.

You can extract it:

type Order = {
  id: string;
  total: number;
  customerType: "STANDARD" | "PREMIUM";
  country: string;
  paymentMethod: "CARD" | "TRANSFER";
};

function calculateOrderTotal(order: Order): number {
  let total = order.total;

  if (order.customerType === "PREMIUM") {
    total *= 0.9;
  }

  if (
    order.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    total -= 500;
  }

  return Math.max(total, 0);
}

Now:

pricing behavior

is no longer coupled to:

MySQL
Stripe

This doesn't require a complete domain-driven redesign. It's simply a useful separation.

The next migration step can replace infrastructure while leaving this behavior unchanged.

Introduce Seams Around Hard Dependencies

Legacy code often contains dependencies that can't easily be replaced in tests or migration code.

For example:

class OrderService {
  async process(orderId: string) {
    const client = new LegacyDatabaseClient();

    const order = await client.findOrder(orderId);

    // ...
  }
}

The database dependency is created inside the method.

That makes substitution difficult.

A small preparatory refactor can introduce a seam:

interface OrderRepository {
  findById(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

Then:

class OrderService {
  constructor(
    private readonly orders: OrderRepository
  ) {}

  async process(orderId: string) {
    const order = await this.orders.findById(orderId);

    if (!order) {
      throw new Error("Order not found");
    }

    // existing behavior
  }
}

Now the existing MySQL implementation can satisfy the interface:

class MySqlOrderRepository implements OrderRepository {
  async findById(id: string) {
    // existing MySQL behavior
  }

  async save(order: Order) {
    // existing MySQL behavior
  }
}

Later, the migration can introduce:

class PostgresOrderRepository implements OrderRepository {
  // new implementation
}

Notice what we didn't change: we didn't change the business behavior. We changed the replaceability of a dependency.

That's exactly the kind of refactoring that helps migration.

Isolate Side Effects from Decision Logic

Another useful separation is between:

deciding

and:

performing

Suppose cancellation currently looks like this:

async function cancelOrder(order: Order) {
  if (order.status === "SHIPPED") {
    throw new Error("Cannot cancel shipped order");
  }

  order.status = "CANCELLED";

  await orders.save(order);
  await inventory.release(order.id);
  await payment.refund(order.id);
  await audit.log("ORDER_CANCELLED", order.id);
}

There are two different responsibilities here.

The business decision:

Can this order be cancelled?
What should its new state be?

And the operational effects:

persist
release inventory
refund
audit

You could first extract the decision:

function cancelOrderState(order: Order): Order {
  if (order.status === "SHIPPED") {
    throw new Error("Cannot cancel shipped order");
  }

  return {
    ...order,
    status: "CANCELLED",
  };
}

Then orchestration remains:

async function cancelOrder(order: Order) {
  const cancelled = cancelOrderState(order);

  await orders.save(cancelled);
  await inventory.release(cancelled.id);
  await payment.refund(cancelled.id);
  await audit.log("ORDER_CANCELLED", cancelled.id);

  return cancelled;
}

The behavior is still the same, but now the state transition can be tested and migrated independently.

That matters if the target architecture changes how side effects are executed.

For example, the future version might use:

transactional outbox
event-driven workflow
queue
workflow engine

You don't need to introduce those mechanisms yet. You only need to stop the current decision logic from depending directly on them.

Put External Systems Behind Adapters

External SDKs often leak deeply into legacy code.

For example:

const result = await stripe.paymentIntents.create({
  amount: order.total,
  currency: "usd",
  metadata: {
    orderId: order.id,
  },
});

If dozens of application modules depend directly on the Stripe SDK, replacing or relocating payment processing becomes difficult.

Create an application-level boundary instead:

type PaymentRequest = {
  orderId: string;
  amount: number;
};

type PaymentResult = {
  paymentId: string;
};

interface PaymentGateway {
  charge(
    request: PaymentRequest
  ): Promise<PaymentResult>;
}

The Stripe adapter contains the provider-specific details:

class StripePaymentGateway implements PaymentGateway {
  async charge(
    request: PaymentRequest
  ): Promise<PaymentResult> {
    const result =
      await stripe.paymentIntents.create({
        amount: request.amount,
        currency: "usd",
        metadata: {
          orderId: request.orderId,
        },
      });

    return {
      paymentId: result.id,
    };
  }
}

The application now knows about:

PaymentGateway

instead of:

Stripe SDK

This is useful for migration because provider-specific code is localized.

The same pattern works for:

email providers
message brokers
cloud storage
ERP integrations
CRM APIs
identity providers
search engines

The adapter isn't valuable because interfaces are fashionable. It's valuable because it creates a boundary you can move.

Improve Dependency Direction Without Rebuilding Everything

Legacy systems often have dependency relationships such as:

business logic
    ↓
database SDK
    ↓
framework utilities

That makes infrastructure difficult to replace.

You don't necessarily need to implement full Clean Architecture. You only need to improve dependency direction where migration requires it.

For example:

Before:

OrderService
   ↓
MySQL

After:

OrderService
   ↓
OrderRepository
   ↑
MySqlOrderRepository

The application depends on an abstraction. The infrastructure implements it.

The same can happen with payments:

OrderService
   ↓
PaymentGateway
   ↑
StripePaymentGateway

and messaging:

OrderService
   ↓
OrderEvents
   ↑
KafkaOrderEvents

Now replacing infrastructure no longer requires rewriting the application service. That's the important outcome.

Extract a Cohesive Application Boundary

After several small refactors, the capability may start to look like this:

interface OrderRepository {
  findById(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

interface PaymentGateway {
  charge(request: {
    orderId: string;
    amount: number;
  }): Promise<void>;
}

interface OrderEvents {
  processed(order: Order): Promise<void>;
}

class ProcessOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly payments: PaymentGateway,
    private readonly events: OrderEvents
  ) {}

  async execute(orderId: string) {
    const order = await this.orders.findById(orderId);

    if (!order) {
      throw new Error("Order not found");
    }

    const total = calculateOrderTotal(order);

    const processed: Order = {
      ...order,
      total,
      status: "PROCESSED",
    };

    await this.orders.save(processed);

    await this.payments.charge({
      orderId: processed.id,
      amount: processed.total,
    });

    await this.events.processed(processed);

    return processed;
  }
}

This isn't necessarily the final architecture. That's important.

We aren't claiming:

This is how the application should look forever.

We're just saying:

This capability now has boundaries that make migration easier.

The infrastructure can change independently.

The business rules are testable. The orchestration is visible. And the external contracts are explicit.

That's enough to start considering migration.

Keep Behavioral Tests Running During the Refactor

This is where the characterization tests from the previous step become useful.

Suppose the original behavior was protected with:

it("preserves premium order processing behavior", async () => {
  const result = await processOrder("order-1");

  expect(result.total).toBe(9000);
  expect(result.status).toBe("PROCESSED");

  expect(payment.charge).toHaveBeenCalledWith({
    orderId: "order-1",
    amount: 9000,
  });

  expect(events.processed).toHaveBeenCalled();
});

Now you can change:

direct database access

into:

repository

and run the test.

Then change:

direct payment SDK

into:

payment adapter

and run the test.

Then extract:

pricing logic

and run the test.

The rhythm becomes:

small structural change
↓
test
↓
small structural change
↓
test
↓
small structural change
↓
test

This matters because structural refactoring is much easier to reason about when behavioral changes aren't happening at the same time.

If a test fails after one small change, the possible cause is narrow.

If a test fails after a two-week rewrite, the possible cause is almost everything.

How to Use AI During Structural Refactoring

AI can help a lot during this phase.

But the useful prompts are different from:

Refactor this application using Clean Architecture.

Instead, give the model a constrained transformation.

For example:

This service currently accesses MySQL directly.

I want to introduce an OrderRepository seam without
changing observable behavior.

Tasks:

1. identify every database operation used by this service,
2. propose the smallest repository interface needed,
3. move existing database calls behind an adapter,
4. preserve return values, errors, and call order where relevant,
5. do not change business rules,
6. do not introduce additional abstractions.

Explain every structural change before generating code.

That gives AI a much narrower job.

Another useful request is:

Compare the implementation before and after this refactor.

Identify any observable behavior that may have changed.

Check specifically:

- exceptions,
- return values,
- side effects,
- ordering of side effects,
- null handling,
- transaction boundaries,
- retry behavior.

Do not assume equivalence because the code looks similar.

This is where AI can be valuable as a second reviewer.

It can inspect differences faster than you can manually scan large changes. But the tests still provide stronger evidence.

Don't Ask AI to Design the Target Architecture Too Early

AI is very good at recognizing common architecture patterns. But that can also be dangerous.

Give a model a large legacy service and ask:

How should this be modernized?

and you may receive:

microservices
event-driven architecture
CQRS
repository pattern
domain events
message broker
API gateway
distributed cache

All of those are legitimate technologies or patterns, but none of them are automatically justified.

Before choosing a target architecture, you need constraints.

For example:

deployment frequency
team size
transactional requirements
latency
failure tolerance
data ownership
integration boundaries
operational maturity
traffic
cost
regulatory requirements

A monolith with good boundaries may be a better target than microservices. A synchronous workflow may be better than event-driven processing. And a database migration may not require changing the domain model.

Architecture should follow constraints, not pattern recognition.

Use AI to evaluate options. Don't let the presence of a familiar pattern become the reason to adopt it.

How to Know When a Capability Is Ready to Migrate

At some point, you have to stop refactoring. And that decision matters.

You don't need perfect code. A capability is usually much closer to migration-ready when you can answer these questions clearly.

Can I Describe its Inputs?

For example:

orderId
customer
request payload
event

Can I Describe its Outputs?

For example:

processed order
HTTP response
event
database change

Are its Important Business Rules Visible?

They don't have to be perfect, but you should know where they live.

Are External Dependencies Explicit?

For example:

OrderRepository
PaymentGateway
OrderEvents
EmailSender

Can Infrastructure Be Substituted?

If replacing MySQL requires changing pricing logic, the boundary is probably not ready.

Are Important Behaviors Protected?

You should have enough tests to detect accidental changes.

Do You Know the Side Effects?

For example:

persist order
create payment
publish event
send email

Are Major Unknowns Documented?

Some uncertainty may remain. But it shouldn't be invisible.

If you can answer those questions, you probably have enough structure to begin migrating that capability.

A Practical Pre-Migration Refactoring Workflow

Here's the workflow I would use.

1. Choose One Capability

Don't refactor the whole application.

Pick:

Process Order
Generate Invoice
Renew Subscription

2. Confirm Behavioral Protection

Before structural changes, make sure critical behavior has tests.

Capture:

outputs
state transitions
side effects
errors
contracts

3. Identify Migration Blockers

Look for coupling such as:

direct database access
provider SDKs
global state
framework-specific objects
static dependencies
shared mutable state

4. Extract Pure Business Logic Where Possible

Move calculations and decisions away from infrastructure.

For example:

calculate price
validate transition
choose status
calculate commission

5. Introduce Seams

Create minimal boundaries around:

database
payments
events
email
storage
external APIs

Don't create abstractions without a migration reason.

6. Localize Infrastructure

Move technology-specific behavior into adapters.

For example:

MySqlOrderRepository
StripePaymentGateway
KafkaOrderEvents
SendGridEmailSender

7. Make Orchestration Visible

Aim for a capability where the sequence is understandable:

load
↓
decide
↓
persist
↓
perform side effects
↓
return

8. Run Behavioral Tests After Every Step

Don't batch ten refactors together. Keep the changes small.

9. Compare Before and After

Check:

inputs
outputs
errors
side effects
data shapes
ordering
transactions

10. Stop When Migration Becomes Possible

Don't continue refactoring because the code could still be cleaner. It always could.

The objective is migration readiness.

What Not to Refactor Before Migration

There are several things I would usually avoid changing during this phase unless they directly block migration.

Naming Everywhere

You may dislike hundreds of old names. But renaming everything produces large diffs with little migration value.

Formatting the Entire Repository

Same problem. Noise makes behavioral changes harder to review.

Replacing Every Pattern

A legacy system may contain:

singletons
service locators
static utilities
large classes

Some may remain temporarily. Fix the ones crossing your migration boundary.

Rewriting Stable Algorithms

If an old calculation is ugly but protected and isolated, it may be safer to move it first and improve it later.

Fixing Every Discovered Bug

This one is especially important.

If you discover a bug while preparing a migration, record it. Then decide whether fixing it belongs in the same change.

Mixing:

structural refactor
+
behavioral correction
+
platform migration

makes failures much harder to understand.

Sometimes the right answer is:

preserve bug
migrate
fix bug intentionally afterward

That sounds uncomfortable. But accidental behavior changes during migration can be much more dangerous.

Refactoring Is Preparation, Not the Migration

It's easy for pre-migration refactoring to become an endless architecture project.

You start with:

We need to isolate the database.

Then:

We should redesign the domain model.

Then:

Maybe we should introduce events.

Then:

If we're doing that, maybe this should become a microservice.

Months later, nothing has migrated. The refactor has become the project.

That's a failure mode, too. The objective should remain concrete.

Before:

ProcessOrder
├── MySQL
├── pricing rules
├── Stripe
├── Kafka
├── email
└── framework internals

After:

ProcessOrder
├── OrderRepository
├── pricing rules
├── PaymentGateway
├── OrderEvents
└── EmailSender

That may be enough.

Now you have choices.

You can migrate:

MySQL → PostgreSQL

without redesigning pricing.

You can replace:

Stripe adapter

without changing order orchestration.

You can move:

ProcessOrder

into another runtime while preserving its contracts.

The refactor created options. That's the value.

Conclusion

Legacy migrations become risky when several types of change happen at once.

You change:

behavior
architecture
infrastructure
runtime
data
deployment

and then try to understand which change caused the failure.

A safer approach is to reduce that uncertainty before migration begins.

First understand the capability, then characterize its behavior, and then change its structure without intentionally changing what it does.

Create boundaries around dependencies. Separate business decisions from infrastructure. Localize external systems. Keep side effects visible. Run behavioral tests after every structural change. And stop refactoring when the capability becomes movable.

The sequence becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate

AI can make the refactoring phase dramatically faster.

It can identify dependencies, extract interfaces, move calls behind adapters, compare implementations, and review large diffs.

But faster refactoring doesn't remove the need for architectural judgment. It makes that judgment more important.

Because the goal isn't to produce the cleanest version of the legacy system. The goal is to create just enough structure to move it safely.

And once you can change the infrastructure without changing the behavior, migration stops looking like a rewrite.

It starts looking like a sequence of controlled changes.

You find a function that's difficult to understand. Or you see duplicated logic, deeply nested conditions, database calls mixed with business rules, and dependencies that make testing almost impossible.

You know the code could be better, so you start cleaning it up.

Then something breaks. Not because the new implementation is obviously wrong. It breaks because the old implementation was doing something nobody knew it was doing.

That's one of the most common risks in legacy modernization.

Before changing code, you need a way to answer a simple question:

Did I preserve the behavior that already mattered?

That is where characterization tests become useful.

A characterization test doesn't begin by asking what the software should do. It begins by documenting what the software does today.

That distinction matters.

In a greenfield application, tests usually express intended behavior. But in a legacy application, you may first need tests that capture existing behavior so you can change the implementation without accidentally changing its observable results.

In this tutorial, I'll show you how to use characterization tests as a safety net before refactoring legacy code.

We'll look at how to:

• identify behavior worth protecting,

• choose useful test boundaries,

• capture current outputs,

• deal with side effects,

• handle databases and external systems,

• use AI to accelerate test discovery,

• avoid freezing implementation details,

• decide what not to characterize,

• and turn characterization tests into a foundation for safer refactoring.

The examples use TypeScript and Vitest, but the approach applies to most languages and testing frameworks.

The goal isn't to preserve every line of legacy behavior forever. The goal is to make behavior visible before you start changing the code that produces it.

Prerequisites

You should be comfortable with:

• TypeScript or a similar programming language

• unit and integration testing

• dependency injection

• mocks and test doubles

• basic refactoring techniques

• reading an unfamiliar codebase

It also helps if you've already mapped the capability you want to change.

Before writing characterization tests, you should have some idea of:

• where the behavior starts

• what state it changes

• which external systems it touches

• which outputs may be consumed elsewhere

Table of Contents

• Prerequisites

• What Characterization Tests Actually Protect

• Start with Behavior, Not Implementation

• Choose One Capability Before Writing Tests

• Find the Smallest Useful Test Boundary

• Capture Existing Behavior Before Improving It

• Characterize Edge Cases You Don't Yet Understand

• Test Side Effects, Not Just Return Values

• How to Characterize Code That Depends on a Database

• How to Handle External Services

• How to Use AI to Discover Characterization Tests

• Don't Let AI Invent Expected Behavior

• Avoid Testing Implementation Details

• When a Characterization Test Reveals a Bug

• How Much Behavior Should You Characterize

• Use Characterization Tests During the Refactor

• A Practical Characterization Testing Workflow

• What Characterization Tests Can't Tell You

• Characterization Tests Are Temporary Knowledge Infrastructure

• Conclusion

What Characterization Tests Actually Protect

Suppose you inherit this function:

type Customer = {
  id: string;
  type: "STANDARD" | "PREMIUM";
};

type Order = {
  id: string;
  customer: Customer;
  subtotal: number;
  country: string;
  paymentMethod: "CARD" | "TRANSFER";
};

async function processOrder(order: Order) {
  let total = order.subtotal;

  if (order.customer.type === "PREMIUM") {
    total = total * 0.9;
  }

  if (order.country === "AR" && order.paymentMethod === "TRANSFER") {
    total = total - 500;
  }

  if (total < 0) {
    total = 0;
  }

  await ordersRepository.save({
    ...order,
    total,
    status: "PROCESSED",
  });

  await eventBus.publish("order.processed", {
    orderId: order.id,
    total,
  });

  return total;
}

There are several things you may want to refactor here.

For example, the pricing rules could move to another module. Persistence could be isolated. The event publisher could sit behind an interface. And the function could return an object rather than a primitive.

Those may all be good decisions, but before making them, you should ask: What behavior currently matters?

For this function, observable behavior includes at least:

• premium customers receive a 10% discount

• Argentine transfers receive another adjustment

• totals can't become negative

• the order is persisted with a specific status

• an event is published

• the event contains the calculated total

• the function returns that total

A characterization test gives you a baseline for those behaviors.

For example:

import { describe, expect, it, vi } from "vitest";

describe("processOrder", () => {
  it("applies the existing premium customer behavior", async () => {
    const save = vi.spyOn(ordersRepository, "save");
    const publish = vi.spyOn(eventBus, "publish");

    const order: Order = {
      id: "order-1",
      customer: {
        id: "customer-1",
        type: "PREMIUM",
      },
      subtotal: 10000,
      country: "US",
      paymentMethod: "CARD",
    };

    const result = await processOrder(order);

    expect(result).toBe(9000);

    expect(save).toHaveBeenCalledWith(
      expect.objectContaining({
        id: "order-1",
        total: 9000,
        status: "PROCESSED",
      })
    );

    expect(publish).toHaveBeenCalledWith("order.processed", {
      orderId: "order-1",
      total: 9000,
    });
  });
});

This test isn't saying that a 10% discount is the best pricing model.

It's saying:

This is what the system currently does.

That's the contract you need to understand before changing it.

Start with Behavior, Not Implementation

A common mistake is to write tests around the structure you're planning to create.

Suppose you want to refactor the previous code into:

OrderProcessor
PricingPolicy
OrdersRepository
OrderEventPublisher

You may be tempted to write tests for those future classes first.

But those classes don't describe the existing system. They describe your proposed design.

Characterization tests should begin at the current observable boundary.

Instead of asking:

How should PricingPolicy work?

ask:

Given this input, what does processOrder() currently produce?

That difference helps prevent your new architecture from redefining behavior accidentally.

The sequence should be:

Observe existing behavior
↓
Capture it
↓
Refactor implementation
↓
Run characterization tests
↓
Verify behavior remains stable

Not:

Design new architecture
↓
Write tests for new architecture
↓
Assume it matches the old system

The second workflow tests your design. The first protects the migration.

Choose One Capability Before Writing Tests

Don't start by trying to characterize an entire legacy application. Instead, pick one business capability.

For example:

Approve Order
Generate Invoice
Renew Subscription
Register Customer
Calculate Commission
Cancel Reservation

Then trace that capability through the system.

Suppose you choose:

Generate Invoice

You discover this path:

POST /orders/:id/invoice
        ↓
InvoiceController.generate()
        ↓
InvoiceService.generate()
        ↓
TaxCalculator.calculate()
        ↓
InvoiceRepository.save()
        ↓
PdfGenerator.create()
        ↓
EmailService.send()

That becomes the scope of your investigation.

Now ask: Which behaviors matter if I refactor this capability?

Perhaps:

tax calculation
invoice numbering
database state
PDF fields
email recipient
email attachment
error behavior

Those are candidates for characterization.

This is more useful than trying to increase test coverage across the repository indiscriminately.

Coverage isn't the goal. Behavioral confidence is.

Find the Smallest Useful Test Boundary

Characterization tests can exist at different levels.

You might test:

function
service
module
API endpoint
background job
complete workflow

The right boundary is usually the smallest one that still captures meaningful behavior.

Suppose the logic you want to refactor lives inside:

class InvoiceService {
  async generate(orderId: string) {
    // 300 lines of legacy behavior
  }
}

If generate() coordinates tax calculation, persistence, numbering, and external calls, testing a small internal helper may not protect enough behavior.

Testing the whole production stack may be too slow and difficult.

A service-level characterization test may be the useful compromise.

For example:

describe("InvoiceService.generate", () => {
  it("preserves the existing invoice calculation", async () => {
    const service = createInvoiceService();

    const invoice = await service.generate("order-123");

    expect(invoice.subtotal).toBe(10000);
    expect(invoice.tax).toBe(2100);
    expect(invoice.total).toBe(12100);
  });
});

You don't want to ask what's the smallest unit you can test. You want to ask what's the smallest boundary that gives you confidence during this refactor.

Those aren't always the same thing.

Capture Existing Behavior Before Improving It

Legacy code often contains behavior that looks suspicious.

Consider:

function calculateDiscount(amount: number) {
  if (amount > 10000) {
    return amount * 0.15;
  }

  if (amount > 5000) {
    return amount * 0.1;
  }

  return 0;
}

You run a few examples and discover:

5000  -> 0
5001  -> 500.1
10000 -> 1000
10001 -> 1500.15

You might think:

5000 should probably receive the 10% discount.

Maybe. But that's not what the current code does.

A characterization test could record:

describe("calculateDiscount", () => {
  it.each([
    [5000, 0],
    [5001, 500.1],
    [10000, 1000],
    [10001, 1500.15],
  ])(
    "returns the existing discount for amount %d",
    (amount, expected) => {
      expect(calculateDiscount(amount)).toBe(expected);
    }
  );
});

This creates a behavioral boundary around the existing implementation.

Later, if the business confirms that 5000 should receive a discount, you can intentionally change:

if (amount > 5000)

to:

if (amount >= 5000)

and update the relevant test.

The important part is that the change becomes explicit.

Without the test, it could happen accidentally during an unrelated refactor.

Characterize Edge Cases You Don't Yet Understand

The obvious cases aren't always the risky ones. Legacy systems often fail at boundaries.

Look for values such as:

0
-1
null
empty string
maximum value
minimum value
exact threshold values
unknown status
duplicate identifiers
missing related records

Suppose you find:

function normalizeBalance(balance?: number) {
  if (!balance) {
    return 0;
  }

  return Math.round(balance * 100) / 100;
}

That means:

undefined -> 0
0         -> 0

But also potentially:

NaN -> 0

because NaN is falsy.

Is that intentional? You may not know yet.

You can characterize it:

describe("normalizeBalance", () => {
  it("returns zero for undefined", () => {
    expect(normalizeBalance(undefined)).toBe(0);
  });

  it("returns zero for zero", () => {
    expect(normalizeBalance(0)).toBe(0);
  });

  it("returns zero for NaN in the current implementation", () => {
    expect(normalizeBalance(Number.NaN)).toBe(0);
  });
});

The name matters.

Notice that I wrote:

in the current implementation

I'm not pretending that behavior is correct. I'm just documenting it.

That distinction becomes important when a test describes questionable behavior.

Test Side Effects, Not Just Return Values

A return value is only one kind of behavior.

Legacy functions frequently produce side effects.

Consider:

async function cancelOrder(order: Order) {
  order.status = "CANCELLED";

  await orders.save(order);
  await inventory.release(order.id);
  await audit.log("ORDER_CANCELLED", order.id);

  return order;
}

A weak characterization test might only check:

expect(result.status).toBe("CANCELLED");

But a refactor could still accidentally remove:

inventory.release()
audit.log()

and the test would continue passing.

A stronger characterization test captures observable side effects:

it("preserves cancellation side effects", async () => {
  const save = vi.spyOn(orders, "save");
  const release = vi.spyOn(inventory, "release");
  const log = vi.spyOn(audit, "log");

  const order = {
    id: "order-1",
    status: "APPROVED",
  } as Order;

  await cancelOrder(order);

  expect(save).toHaveBeenCalled();

  expect(release).toHaveBeenCalledWith("order-1");

  expect(log).toHaveBeenCalledWith(
    "ORDER_CANCELLED",
    "order-1"
  );
});

This doesn't mean every internal call deserves an assertion.

The question is whether the call produces observable behavior that matters outside the implementation.

How to Characterize Code That Depends on a Database

Database-heavy legacy code can be difficult to test.

Suppose you have:

async function activateCustomer(customerId: string) {
  const customer = await db.customers.findById(customerId);

  if (!customer) {
    throw new Error("Customer not found");
  }

  await db.customers.update(customerId, {
    status: "ACTIVE",
    activatedAt: new Date(),
  });

  return db.customers.findById(customerId);
}

You have several options.

Use an Integration Test

If the database behavior itself matters, run against a disposable test database.

For example:

it("activates an existing customer", async () => {
  await seedCustomer({
    id: "customer-1",
    status: "PENDING",
  });

  const result = await activateCustomer("customer-1");

  expect(result?.status).toBe("ACTIVE");
  expect(result?.activatedAt).toBeTruthy();
});

This gives high confidence, but the test may be slower.

Introduce a Seam

If database access makes testing impractical, you may need a very small structural change before characterization.

For example:

type CustomerRepository = {
  findById(id: string): Promise<Customer | null>;
  update(
    id: string,
    data: Partial<Customer>
  ): Promise<void>;
};

Then:

async function activateCustomer(
  customerId: string,
  customers: CustomerRepository
) {
  // existing behavior
}

This is a useful concept from legacy-code work: create a seam, a place where behavior can be observed or replaced without rewriting the system.

The key is to keep this preparatory change mechanical.

Don't redesign the business logic while creating the test boundary.

First make it testable. Then characterize it. Then refactor.

How to Handle External Services

Legacy code frequently talks directly to:

payment providers
email services
ERPs
CRMs
message brokers
cloud storage
third-party APIs

You usually don't want characterization tests repeatedly calling those systems.

Instead, capture the interaction at the boundary.

Suppose:

async function chargeOrder(order: Order) {
  const response = await stripe.charge({
    amount: order.total,
    currency: "usd",
    customerId: order.customerId,
  });

  await orders.markPaid(order.id, response.id);

  return response.id;
}

You can characterize the request:

it("sends the existing payment payload", async () => {
  const charge = vi
    .spyOn(stripe, "charge")
    .mockResolvedValue({
      id: "payment-123",
    });

  const markPaid = vi.spyOn(orders, "markPaid");

  const order = {
    id: "order-1",
    total: 5000,
    customerId: "customer-1",
  } as Order;

  await chargeOrder(order);

  expect(charge).toHaveBeenCalledWith({
    amount: 5000,
    currency: "usd",
    customerId: "customer-1",
  });

  expect(markPaid).toHaveBeenCalledWith(
    "order-1",
    "payment-123"
  );
});

That protects the external contract without hitting the external system.

But be careful. If the provider behavior itself matters, mocks alone may not be enough.

You might also need:

• provider sandbox tests

• contract tests

• integration tests

• schema validation

Characterization testing doesn't eliminate the need for those layers.

How to Use AI to Discover Characterization Tests

AI is particularly useful when you are staring at a large legacy function and trying to understand what deserves a test.

Suppose you have a 400-line service.

Instead of asking:

Write unit tests for this class.

use a more investigative prompt:

Analyze this class without changing it.

Identify observable behaviors that could change during refactoring.

Group them into:

1. returned values,
2. state changes,
3. persistence effects,
4. external calls,
5. emitted events,
6. exceptions,
7. boundary conditions.

For every proposed characterization test:

- reference the relevant source code,
- explain what behavior the test would protect,
- distinguish observed behavior from inferred behavior.

Do not invent expected values.

That final instruction matters: you want AI to help identify what to observe. You don't want it inventing what the software should do.

Another useful prompt is:

Review the existing test suite for this capability.

Compare the behaviors covered by tests with the
observable behaviors in the implementation.

List behavior that appears unprotected.

Do not generate tests yet.

This is often more valuable than immediately asking for test code.

First identify the gaps, and then decide which gaps matter.

Don't Let AI Invent Expected Behavior

This is probably the most important rule when combining AI with characterization testing, and it's worth talking a bit more about.

Suppose AI reads:

if (customer.age > 65) {
  discount = 0.2;
}

It may generate:

expect(calculateDiscount(65)).toBe(0.2);

because it assumes the intended business rule is:

Customers aged 65 or older receive a discount.

But that's not what the code says.

The existing behavior is:

65 -> no discount
66 -> discount

The expected values in characterization tests should come from evidence.

Useful evidence includes:

• running the current system

• existing tests

• fixtures

• production-safe observations

• documented examples

• database state

• historical behavior

Don't derive expectations solely from what seems reasonable.

A better AI instruction is:

For each candidate test, tell me how I can obtain
the expected result from the current implementation.

Do not propose the expected result yourself unless it
can be directly derived from executable behavior
or an existing test.

This turns AI into an assistant for experiment design rather than an authority on business rules.

Avoid Testing Implementation Details

Characterization tests can become harmful if they freeze the current code structure.

Suppose the implementation is:

async function processOrder(order: Order) {
  validateOrder(order);
  calculatePrice(order);
  reserveInventory(order);
  saveOrder(order);
}

A brittle test might assert:

expect(validateOrder).toHaveBeenCalledBefore(calculatePrice);
expect(calculatePrice).toHaveBeenCalledBefore(reserveInventory);
expect(reserveInventory).toHaveBeenCalledBefore(saveOrder);

Maybe that order matters. Maybe it doesn't.

If consumers only care about:

correct total
inventory reserved
order persisted

then asserting the exact sequence unnecessarily constrains the refactor.

Prefer protecting externally meaningful behavior.

For example:

expect(savedOrder.total).toBe(9000);
expect(inventory.reserve).toHaveBeenCalledWith(
  "product-1",
  2
);
expect(repository.save).toHaveBeenCalled();

Characterization tests should create a safety net. They shouldn't turn the legacy implementation into a specification of every internal decision.

When a Characterization Test Reveals a Bug

Eventually you'll encounter behavior that appears clearly wrong.

For example:

function calculateFee(amount: number) {
  if (amount === 0) {
    return 100;
  }

  return amount * 0.02;
}

You confirm that zero-value transactions are charged a fixed fee. Everyone agrees this looks suspicious.

What should the characterization test do?

First, separate two questions:

1. What does the system do today?

2. What should the system do?

The characterization test answers the first.

it("currently charges 100 for a zero-value transaction", () => {
  expect(calculateFee(0)).toBe(100);
});

Then investigate whether this is intentional business behavior, a historical workaround, or an actual defect.

If the business confirms it is a bug, create a separate change.

For example:

it("does not charge a fee for a zero-value transaction", () => {
  expect(calculateFee(0)).toBe(0);
});

Then modify the production code.

This may sound overly formal for a small condition. But it creates a clean distinction between:

behavior discovered during refactoring

and:

behavior intentionally changed

That distinction becomes extremely valuable in large migrations.

How Much Behavior Should You Characterize

You don't need to characterize everything. Trying to preserve every observed detail can create another form of paralysis.

Prioritize behavior with high change risk or high business impact.

I usually look first at:

• financial calculations

• state transitions

• authentication and authorization

• external contracts

• queue and event payloads

• data transformations

• retry behavior

• idempotency

• regulatory rules

• critical error handling

You may care less about:

• internal helper naming

• private method structure

• log wording that nobody consumes

• temporary object shapes

• implementation-specific call sequences

A useful question is: If this behavior changed during refactoring, could somebody outside this function notice?

If the answer is yes, it's probably worth considering.

Use Characterization Tests During the Refactor

Once the characterization suite exists, keep the refactor small.

Suppose you begin with:

async function processOrder(order: Order) {
  // validation
  // pricing
  // inventory
  // persistence
  // event publishing
}

You might first extract pricing:

function calculateOrderTotal(order: Order) {
  let total = order.subtotal;

  if (order.customer.type === "PREMIUM") {
    total *= 0.9;
  }

  if (
    order.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    total -= 500;
  }

  return Math.max(total, 0);
}

Run the characterization suite. If everything still passes, continue.

Next isolate inventory and run it again.

Then persistence. Run it again.

This gives you a migration rhythm:

small structural change
↓
run tests
↓
observe
↓
continue

If something fails, the search space is small.

Compare that with rewriting 2,000 lines and then discovering 47 broken tests.

Small changes turn failures into useful feedback, while Large changes turn failures into archaeology.

Again.

A Practical Characterization Testing Workflow

Here is the workflow I would use on an unfamiliar legacy capability.

1. Map the Capability

Identify:

entry point
business logic
state changes
side effects
external contracts
outputs

Don't refactor yet.

2. Find Existing Tests

Search for tests that already describe the capability.

Look for:

happy paths
boundary cases
errors
historical bugs
integration behavior

Don't duplicate useful tests unnecessarily.

3. List Observable Behaviors

Create a table such as:

Now you know where the risk is.

4. Pick the Test Boundary

Decide whether the useful boundary is:

function
service
module
endpoint
job
workflow

Choose based on confidence, not test ideology.

5. Capture Current Behavior

Run the existing system.

Use real observable outputs when possible.

Don't guess expectations.

6. Add Critical Edge Cases

Test:

thresholds
empty values
nulls
errors
duplicate operations
retry scenarios

especially around logic you intend to change.

7. Capture Side Effects

Protect meaningful:

writes
events
messages
external calls
state transitions

not only function return values.

8. Mark Uncertain Behavior

Use test names or documentation that clearly distinguishes:

confirmed business rule

from:

current observed behavior

9. Refactor Incrementally

Make one structural change.

Run the suite.

Repeat.

10. Replace Characterization with Intent Where Appropriate

As understanding improves, some characterization tests can evolve into true specification tests.

Instead of:

currently returns 0 for this input

you may eventually be able to say:

does not apply a discount below the premium threshold

That transition is useful. It means the system is becoming understood rather than merely preserved.

What Characterization Tests Can't Tell You

Characterization tests are powerful, but they have an important limitation.

They tell you what happened for the cases you observed. They don't automatically tell you why.

Suppose the test says:

Argentine transfer orders receive a 500-unit adjustment.

The test can protect that behavior.

It can't tell you whether the adjustment exists because of:

• a tax rule

• a banking fee

• an old promotion

• a customer-specific workaround

• a bug nobody removed

For that, you still need other evidence:

• documentation

• Git history

• production telemetry

• domain experts

• incident records

• external system contracts

This is why characterization testing belongs after codebase understanding, not instead of it.

You first discover the behavior. Then you protect it. Then you continue investigating what it means.

Characterization Tests Are Temporary Knowledge Infrastructure

There's another way I think about these tests.

Legacy systems contain knowledge that's often trapped inside implementation details. A characterization test moves some of that knowledge into an executable form.

Before:

Nobody knows what changing this condition will break.

After:

Changing this condition causes these four observable behaviors to change.

That's already progress.

The test suite becomes part of your understanding of the system. It creates a bridge between:

what the code currently does

and:

what we eventually want the system to do

You don't have to keep every characterization test forever.

Some will become proper specification tests.

Some will disappear when obsolete behavior is intentionally removed.

Some will remain as regression tests.

Their first job is simpler: make change safer while understanding is still incomplete.

Conclusion

AI makes refactoring legacy code faster.

It can explain functions, generate candidate abstractions, extract interfaces, suggest module boundaries, and rewrite large sections of code in seconds.

That makes characterization testing more important, not less.

When the cost of producing a new implementation decreases, the risk shifts toward verifying that the new implementation still preserves the behavior that matters.

Before asking:

How should I refactor this?

ask:

What does this do today?

Then:

Which of those behaviors matter?

Then:

How can I prove they still work after the change?

That is what characterization tests give you.

They don't tell you that legacy behavior is correct. They give you evidence that it exists.

And once that evidence is executable, you can refactor with much more confidence.

The sequence becomes:

Understand
↓
Characterize
↓
Refactor
↓
Verify

AI can accelerate every step in that workflow. But the engineering judgment remains in deciding what behavior deserves to survive, what behavior should change, and when you have enough evidence to safely make that distinction.

You open a class that's 1,500 lines long. There are database calls mixed with business rules, configuration values scattered across the repository, methods nobody wants to touch, and comments that refer to systems that disappeared years ago.

Then an AI coding assistant offers to explain the whole thing.

So you ask:

Refactor this class.

But that's usually too early.

One of the lessons I've learned from working with legacy systems is that code can be ugly and still contain important knowledge.

A strange condition may encode a business exception. A duplicated calculation may exist because two processes that look identical aren't actually identical. A database column with a terrible name may still be part of an external contract.

And a method nobody understands may be the only thing preventing a production incident that happened eight years ago from happening again.

AI makes it much easier to read unfamiliar software, and that's valuable. But it also makes it much easier to change software before you understand it.

In this tutorial, I'll show you how to use AI for something I believe should happen before refactoring or migration: codebase archaeology.

You'll learn how to use AI to help you:

• map a repository,

• identify entry points,

• trace dependencies,

• separate business rules from infrastructure,

• find hidden side effects,

• inspect data flow,

• discover implicit contracts,

• detect duplicated behavior,

• build a dependency map,

• identify areas of uncertainty,

• and turn those findings into a modernization plan.

The examples use TypeScript, but the process works with most languages and stacks.

The goal isn't to ask AI what the code means and trust the answer. The goal is to use AI to reduce the amount of time you spend looking for the right questions.

Prerequisites

You should be comfortable with:

• reading an existing codebase

• TypeScript or a similar object-oriented language

• basic software architecture

• dependency injection

• unit and integration testing

• using an AI coding assistant that can inspect repository files

You don't need a specific AI provider, as the workflow matters more than the model.

Table of Contents

• Prerequisites

• Why Understanding Has to Come Before Refactoring

• How to Start with the Repository, Not the Classes

• How to Find the Real Entry Points

• How to Trace a Business Capability Through the Codebase

• How to Separate Business Rules from Infrastructure

• How to Find Hidden Side Effects

• How to Discover Implicit Contracts

• How to Use AI to Find Duplicated Business Rules

• How to Build a Lightweight Dependency Map

• How to Mark What You Still Do Not Understand

• How to Validate AI Findings Against the System

• How to Turn Codebase Understanding into a Migration Plan

• A Practical Codebase Archaeology Workflow

• What I Would Not Ask AI to Do First

• The Most Useful AI Output Is Sometimes a Question

• Conclusion

Why Understanding Has to Come Before Refactoring

Legacy code often creates a false sense of urgency.

You see something obviously coupled or duplicated and immediately want to clean it up.

Consider this function:

async function approveOrder(order: Order) {
  if (order.total > 10000 && !order.customer.verified) {
    throw new Error("Manual verification required");
  }

  if (
    order.customer.country === "AR" &&
    order.paymentMethod === "TRANSFER"
  ) {
    order.status = "PENDING";
  } else {
    order.status = "APPROVED";
  }

  await orders.save(order);

  if (order.status === "APPROVED") {
    await billing.createInvoice(order);
  }

  await audit.log({
    action: "ORDER_APPROVAL",
    orderId: order.id,
    status: order.status,
  });

  return order;
}

At first glance, there are several clear refactoring opportunities:

• You could extract validation.

• You could isolate status calculation.

• You could move billing behind an interface.

• You could create an approval policy.

All of those ideas may be reasonable, but there are questions you should answer first:

• Why is 10000 important?

• Why does an Argentine bank transfer remain pending?

• Does invoice creation have to happen after persistence?

• Is ORDER_APPROVAL consumed by another system?

• Can orders transition from PENDING to APPROVED somewhere else?

• Does anything depend on the exact exception message?

You can't answer those questions from syntax alone.

That's where understanding begins.

Instead of asking your AI tool:

Refactor this function using clean architecture.

start with:

Analyze this function without changing it.

Identify:

1. explicit business rules,
2. likely business rules that need confirmation,
3. side effects,
4. external dependencies,
5. state transitions,
6. magic values,
7. assumptions that cannot be proven from this file alone.

Do not propose a refactor yet.

That last line is important: Do not propose a refactor yet.

You want the model in investigation mode, not solution mode.

How to Start with the Repository, Not the Classes

When I approach an unfamiliar legacy system, I don't start by reading every file. I start by trying to understand the shape of the application.

A repository already contains architectural clues.

Look for directories such as:

src/
controllers/
services/
repositories/
models/
jobs/
workers/
scripts/
migrations/
config/
integrations/
tests/

But don't assume the directory names describe the real architecture.

A directory called services can contain business logic, infrastructure, orchestration, and random utility functions.

A directory called models might contain database entities rather than domain models.

A folder called utils can hide half the application's business logic.

Use the structure as evidence, not truth.

A useful first AI request is:

Inspect the repository structure.

Do not analyze individual implementation details yet.

Identify:

- application entry points,
- major modules,
- database technologies,
- external integrations,
- background processing,
- scheduled tasks,
- authentication mechanisms,
- configuration sources,
- tests,
- likely architectural boundaries.

For each conclusion, reference the files or directories
that support it.

Mark anything uncertain explicitly.

The requirement to reference files matters. Without it, AI can give you a perfectly reasonable architecture that doesn't actually exist.

You want something closer to:

HTTP API
Evidence:
- src/server.ts
- src/routes/orders.ts
- src/routes/customers.ts

Background processing
Evidence:
- src/workers/paymentWorker.ts
- src/queues/index.ts

Scheduled jobs
Evidence:
- src/jobs/reconcileInvoices.ts
- src/cron.ts

Now you have a map you can verify.

How to Find the Real Entry Points

Web applications often have an obvious HTTP entry point. But legacy systems frequently have several more.

A business operation may begin from:

• an API request,

• a scheduled job,

• a queue consumer,

• a database trigger,

• a CLI script,

• a file import,

• an email handler,

• a webhook,

• or another application calling the database directly.

If you only analyze controllers, you may miss half the system.

Suppose you search for order creation and find:

POST /orders

It would be easy to assume that all orders enter through that endpoint.

Then you discover:

jobs/importMarketplaceOrders.ts
workers/retryFailedOrders.ts
scripts/migratePendingOrders.ts
integrations/shopify/webhook.ts

Now the same business object has four additional entry paths.

This changes how you think about refactoring.

Ask AI:

Find every location that can create, modify,
approve, cancel, or persist an Order.

Include:

- HTTP endpoints,
- background workers,
- scheduled jobs,
- scripts,
- imports,
- webhooks,
- direct repository calls.

Group the results by operation.

For every result, include the file path and
the relevant function or class.

Then verify those results with repository search.

For example:

rg "orders\.save|orders\.insert|createOrder|approveOrder" src

AI should accelerate search, not replace it.

How to Trace a Business Capability Through the Codebase

Understanding individual files isn't enough.

What usually matters is understanding a business capability.

For example:

Create an order.

That capability may travel through several layers:

HTTP Request
     ↓
Controller
     ↓
Application Service
     ↓
Pricing
     ↓
Inventory
     ↓
Persistence
     ↓
Payment
     ↓
Notification

The code may not be organized that cleanly, and that's precisely why tracing the capability is useful.

Choose one real workflow and ask:

Trace the "Create Order" capability from its entry point
until all observable side effects are complete.

For each step, show:

- file,
- function or class,
- input,
- output,
- state change,
- external call,
- error behavior.

Do not summarize multiple steps into one.

You want a sequence that you can inspect.

For example:

1. POST /orders
   src/routes/orders.ts

2. OrdersController.create()
   src/controllers/OrdersController.ts

3. OrderService.create()
   src/services/OrderService.ts

4. calculatePrice()
   src/services/pricing.ts

5. inventory.reserve()
   src/integrations/inventory.ts

6. ordersRepository.save()
   src/repositories/orders.ts

7. paymentQueue.publish()
   src/queues/payment.ts

This becomes far more useful than a generic explanation of the architecture.

Now you can ask questions such as:

• Where does the transaction actually begin?

• What happens if payment publishing fails?

• Is inventory reservation reversible?

• Can the order be saved twice?

• Which steps are synchronous?

• Which failures are retried?

Those are modernization questions.

How to Separate Business Rules from Infrastructure

One of the most useful things you can do during codebase archaeology is identify where business behavior lives.

Legacy applications frequently mix it with infrastructure.

Consider:

async function saveCustomer(customer: Customer) {
  if (
    customer.type === "ENTERPRISE" &&
    customer.creditLimit < 50000
  ) {
    throw new Error("Invalid enterprise credit limit");
  }

  const connection = await mysql.getConnection();

  await connection.query(
    "INSERT INTO customers (...) VALUES (...)",
    [...]
  );

  await redis.del(`customer:${customer.id}`);

  await eventBus.publish(
    "customer.updated",
    customer
  );
}

There's at least one business rule:

Enterprise customers must have a credit limit >= 50000.

And several infrastructure concerns:

MySQL
Redis
Event bus

Ask AI to classify the code:

Classify each responsibility in this function as one of:

- business rule,
- application orchestration,
- persistence,
- caching,
- messaging,
- logging,
- validation,
- unknown.

Explain why.

Do not move or rewrite any code.

The unknown category is useful. You don't want the model to force every line into a clean architectural theory.

Some code really is ambiguous until you inspect more context.

How to Find Hidden Side Effects

Side effects are one of the biggest sources of migration risk.

A function called:

updateCustomer()

may do much more than update a customer.

It may:

• write to the database

• invalidate cache

• emit an event

• send an email

• update analytics

• write an audit record

• schedule another job

If you refactor the function and preserve only its return value, you can break production behavior without any compiler error.

A useful investigation prompt is:

List every observable side effect produced directly
or indirectly by this function.

For each one, identify:

- the side effect,
- where it happens,
- whether it is synchronous or asynchronous,
- whether failure propagates,
- whether it appears retryable,
- whether it is idempotent,
- whether it can be safely repeated.

Mark uncertain answers as unknown.

That last property, idempotency, matters a lot.

Suppose a worker does this:

await chargeCard(order);
await markOrderAsPaid(order);

If the worker crashes between those two lines and retries, what happens? You may charge the customer twice. And that's not visible from the function name.

Understanding retry semantics is part of understanding the codebase.

How to Discover Implicit Contracts

Not every contract is declared with an interface. Legacy applications contain many implicit contracts.

For example:

return {
  status: "ok",
  value: customer.balance.toFixed(2),
};

Some external consumer may depend on:

{
  "status": "ok",
  "value": "100.00"
}

Changing value from a string to a number can look like an improvement:

{
  "status": "ok",
  "value": 100
}

It can also break a client.

Look for contracts in:

• API responses,

• events,

• database structures,

• CSV exports,

• filenames,

• environment variables,

• error messages,

• queue payloads,

• and webhook bodies.

Ask:

Identify outputs from this module that could be consumed
outside the module.

Include:

- HTTP responses,
- emitted events,
- queue messages,
- files,
- database records,
- exceptions,
- logs used for automated processing.

For each output, explain what evidence suggests that it
may be an external or implicit contract.

The wording matters:

what evidence suggests

not:

tell me which contracts exist

because you may not be able to prove the consumer from the current repository.

How to Use AI to Find Duplicated Business Rules

Duplicated code is easy to detect. Duplicated business meaning is harder.

You may find:

if (customer.type === "PREMIUM") {
  discount = total * 0.1;
}

in one module.

And elsewhere:

if (account.plan === "GOLD") {
  price = price * 0.9;
}

Those might represent the same business rule, or they might not.

AI is useful for identifying candidates.

Ask:

Search the repository for business rules related to
customer discounts.

Group implementations that appear semantically related,
even if variable names differ.

For each group:

- list file locations,
- describe the apparent rule,
- highlight differences,
- do not assume the rules should be unified.

That final instruction is important.

Duplication is sometimes accidental.

Sometimes it represents two domains that evolved independently.

Don't let an AI assistant turn:

similar

into:

must be merged

without evidence.

How to Build a Lightweight Dependency Map

At some point, you need to understand which parts of the system depend on which others.

You don't need a perfect enterprise architecture diagram. A lightweight dependency map is enough to start.

For example:

Orders
 ├── Customers
 ├── Inventory
 ├── Payments
 ├── Notifications
 └── Database

Payments
 ├── Payment Provider
 ├── Audit
 └── Database

Ask AI to extract module-level dependencies:

Build a module dependency map from the repository.

Only include dependencies supported by imports,
constructor dependencies, explicit calls, or configuration.

Output:

Module A -> Module B

For each dependency, provide at least one source file
that demonstrates it.

Do not infer dependencies from names alone.

You can then compare the result with automated tools.

For JavaScript or TypeScript projects, dependency analysis tools can help you find:

• circular dependencies

• cross-module imports

• high fan-in

• high fan-out

AI is useful for explaining why those dependencies may matter. Static analysis is better at proving that they exist.

Use both.

How to Mark What You Still Do Not Understand

This is one of the most important parts of the process.

A useful system map doesn't only contain answers. It also contains uncertainty.

I like keeping an explicit list such as:

## Open Questions

- Why is the enterprise credit threshold 50,000?
- Is `ORDER_APPROVAL` consumed outside this repository?
- Can marketplace orders bypass inventory validation?
- Is `customer.balance` allowed to be negative?
- What process transitions PENDING orders to APPROVED?
- Is `legacy_customer_id` still used by another system?

You can ask AI to generate this list:

Based on everything analyzed so far, list the questions
that can't be answered safely from the repository.

Focus on questions that would matter during:

- refactoring,
- migration,
- schema changes,
- interface changes,
- removal of code.

Do not answer the questions.

I like this prompt because it does the opposite of what we normally ask AI to do. It asks the model to identify where it should not pretend to know.

A modernization plan should include those unknowns.

How to Validate AI Findings Against the System

AI-generated explanations can sound convincing even when they're incomplete. So every important finding should have another source of evidence.

I use a simple hierarchy.

Repository Search

If AI says a function is called only once, search for it.

rg "approveOrder" .

Tests

Tests often reveal assumptions that implementation code doesn't explain.

Look for:

expected errors
special values
boundary cases
fixture data
historical behavior

Database Schema

The schema may reveal key things like:

• nullable fields

• foreign keys

• defaults

• legacy columns

• constraints

• status values

Logs and Observability

Production telemetry can tell you whether a supposedly unused path is still active.

Version History

Git history can sometimes answer questions that source code can't.

For example:

git log -S "Manual verification required" --all

or:

git blame src/orders/approveOrder.ts

The commit that introduced a strange condition may contain the explanation.

This is an area where AI can help summarize history:

Review the commits that changed this function.

Build a timeline of behavior changes.

For each change, include:

- commit,
- date,
- behavior changed,
- stated reason if available.

Do not infer a reason if the commit history does not provide one.

That can save a surprising amount of time.

How to Turn Codebase Understanding into a Migration Plan

Once you understand one capability, you can begin making decisions. But not before.

Suppose your investigation produces this:

Create Order

Business rules:
- active customer required
- premium customers receive 10% discount
- inventory must be available

Side effects:
- order persisted
- inventory reserved
- payment queued
- confirmation email sent

External contracts:
- POST /orders response
- payment queue payload
- order.created event

Unknowns:
- retry semantics for inventory reservation
- whether event consumers require exact field names

Now you can decide what to protect.

For example:

Protect first:
- pricing behavior
- API response
- payment payload
- event schema

Then decide what can be refactored.

Candidate boundaries:
- pricing policy
- inventory gateway
- payment publisher
- notification service

Then decide what needs investigation.

Block migration until understood:
- inventory retry behavior
- event consumers

That's already a migration plan.

Notice what AI did not do: it didn't decide the target architecture.

It helped make the current architecture observable enough for you to make that decision.

A Practical Codebase Archaeology Workflow

If I had to reduce this process to something repeatable, I would use these steps.

1. Map the Repository

Identify:

• entry points

• modules

• persistence

• integrations

• workers

• jobs

• tests

• configuration

Don't refactor anything.

2. Choose One Capability

Pick something concrete:

Create Order
Approve Loan
Generate Invoice
Register Customer
Cancel Subscription

Avoid trying to understand the whole product at once.

3. Trace It End to End

Follow:

input
↓
business logic
↓
state changes
↓
external calls
↓
output

Record every file involved.

4. Extract Business Rules

Separate:

• explicit rules

• likely rules

• infrastructure behavior

• unknowns

5. Identify Side Effects

Find:

• writes

• messages

• emails

• jobs

• cache changes

• external calls

6. Discover Contracts

Look for:

• APIs

• event schemas

• database assumptions

• exported files

• error behavior

7. Map Dependencies

Document:

module -> module

and identify coupling.

8. Record Unknowns

Don't hide uncertainty. Create an explicit list.

9. Verify

Use:

• repository search

• tests

• schema

• logs

• Git history

• production telemetry

10. Only Then Plan the Change

Decide:

• what behavior must survive,

• what code can disappear,

• what boundaries should be introduced,

• what needs tests,

• and what can migrate first.

What I Would Not Ask AI to Do First

There are several prompts I avoid at the beginning of a legacy modernization project.

For example:

Rewrite this application using Clean Architecture.

or:

Convert this monolith into microservices.

or:

Modernize this entire repository.

or even:

Find all the bad code.

The problem isn't that AI can't produce useful output from those prompts. It can.

The problem is that those questions already contain a solution.

You're asking for:

Clean Architecture
Microservices
Rewrite
Bad code

before you've established what the system actually needs.

A better sequence is:

What exists?
↓
Why does it exist?
↓
What behavior matters?
↓
What is uncertain?
↓
What should change?

That sequence is slower for the first hour, but it's usually much faster for the rest of the project.

The Most Useful AI Output Is Sometimes a Question

There's a tendency to evaluate AI coding tools by how much code they generate.

For legacy systems, I think that misses part of their value.

One of the most useful outputs can be:

I cannot determine why this condition exists from the available code.

Or:

This event appears to have no consumer in the current repository, but external consumers cannot be ruled out.

Or:

These two discount calculations look similar, but their behavior differs for zero-value orders.

Those are useful findings that tell an engineer where to investigate.

A confident but incorrect answer is much more dangerous.

When working with legacy systems, uncertainty is information. Treat it that way.

Conclusion

AI makes unfamiliar codebases much easier to explore.

You can use it to summarize modules, trace execution paths, extract candidate business rules, find side effects, compare implementations, analyze Git history, and build dependency maps.

That can remove a large amount of mechanical investigation work.

But understanding a system isn't the same as generating an explanation of it. Legacy applications contain context that may exist outside the source code:

• production behavior,

• old incidents,

• external consumers,

• business exceptions,

• undocumented integrations,

• and organizational history.

AI can help you find evidence. It can't manufacture missing history.

That's why I prefer to use it as an investigator before I use it as a transformer.

Start with:

What does this system actually do?

Then ask:

What do I still not understand?

Only after that should you ask:

What should I change?

The faster AI lets you modify software, the more important that sequence becomes.

Because changing code you understand is engineering. But changing code you don't understand is experimentation.

And production is usually the most expensive place to run that experiment.