<![CDATA[ Hugo Teijiz - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ https://cdn.freecodecamp.org/universal/favicons/favicon.png <![CDATA[ Hugo Teijiz - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ Eleventy Mon, 28 Sep 2026 05:38:18 +0000 60 <![CDATA[ How Executable Operational Specifications Can Make Software Automation Verifiable ]]> https://www.freecodecamp.org/news/executable-operational-specifications-software-automation/ 6ab54b145ca9fc6a257ae996 Thu, 24 Sep 2026 16:08:52 +0000 Modern software systems are increasingly automated. We automate deployments, infrastructure changes, scaling, incident response, and data pipelines.

And now, with AI agents, we are starting to automate operational decisions too. That sounds like progress, but it creates a problem that is easy to miss:

We are getting better at executing operations without necessarily getting better at specifying what those operations are supposed to achieve.

A deployment pipeline can run successfully and still violate an important business constraint.

An infrastructure script can finish without error and still leave the system in the wrong state.

An AI agent can complete a sequence of actions and still produce an outcome that nobody can verify afterward.

In many systems, operational intent still lives across:

runbooks
tickets
Slack messages
CI/CD configuration
Terraform files
dashboards
monitoring rules
human memory

Those artifacts are useful. But they are not the same thing as an executable operational specification.

An executable operational specification describes what should happen in a way that can later be evaluated against what actually happened.

That distinction becomes increasingly important as execution gets faster, more distributed, and more autonomous.

In this article, I'll explore:

  • why automation alone is not enough,

  • the difference between execution logic and operational intent,

  • what an executable operational specification is,

  • why observability does not solve this problem by itself,

  • how specifications can make operational behavior verifiable,

  • how this applies to CI/CD, infrastructure, incident response, and AI agents,

  • what a minimal specification might look like,

  • and what problems this approach still does not solve.

The central idea is simple:

If a system can execute an operation automatically, we should also be able to describe what successful execution means independently of the tool performing it.

Prerequisites

You should be comfortable with:

  • software architecture

  • CI/CD

  • infrastructure automation

  • observability

  • distributed systems

  • basic testing concepts

  • automation workflows

You do not need to use any particular cloud provider, deployment platform, or orchestration tool.

The ideas in this article are deliberately tool-independent.

Table of Contents

Automation Solves Execution, Not Intent

Consider a deployment pipeline. It might:

build the application
run tests
build an image
push the image
deploy it
wait for readiness
mark the pipeline as successful

If every step completes, the pipeline turns green. But what did the pipeline actually prove?

Usually, something like:

the configured steps completed successfully

That is useful. But it is not necessarily the same as:

the intended operational outcome was achieved

Suppose the deployment succeeds technically, but:

the wrong image version was deployed
only two replicas are running instead of three
the error rate increased
a required feature flag is disabled
the service is healthy but cannot reach a dependency
the rollout violated a regional constraint

The executor did its job. The operation still failed in a broader sense. This is the gap between execution success and operational conformance.

Automation tells us:

The steps ran.

What we often need to know is:

Did the resulting system satisfy the intended conditions?

Those are different questions.

Operational Knowledge Is Usually Fragmented

Most production systems already contain operational knowledge. The problem is that it is scattered.

For example, a deployment rule might exist partly in:

GitHub Actions
Terraform
Kubernetes manifests
Grafana dashboards
PagerDuty alerts
a runbook
a ticket
a senior engineer's memory

One artifact might define how many replicas should exist. Another might define what error rate is acceptable. A third might explain when rollback is required. A fourth might describe which regions are allowed.

No single representation says:

This is the operation we intend to perform.

These are its constraints.

This is the evidence we require.

This is how we determine whether it succeeded.

That makes operations harder to reason about. It also makes automation brittle.

When the rules are distributed across tools, the executor often becomes the de facto specification.

And once that happens, it becomes difficult to ask whether the executor behaved correctly.

The logic that performs the action and the logic that defines success are effectively the same thing.

Execution Logic and Operational Intent Are Different Things

Imagine a deployment script:

kubectl set image \
  deployment/orders \
  orders=registry.example.com/orders:2026.09.19

This tells Kubernetes how to perform an action. It does not fully describe why the action is acceptable.

The operational intent might be closer to:

Deploy version 2026.09.19 of the Orders service.

Constraints:

- production must keep at least 3 available replicas
- the error rate must remain below 1%
- p95 latency must stay below 400 ms
- deployment is allowed only in us-east-1
- rollback must remain possible for 30 minutes

The command and the intent are related. But they are not the same artifact.

This distinction matters because several different executors might be able to satisfy the same intent.

For example:

Kubernetes
Nomad
a cloud deployment service
a custom deployment controller
an AI-operated platform

If the operational goal is expressed independently, the executor becomes replaceable.

If the goal is embedded inside executor-specific code, replacing the executor may also mean rediscovering the intent.

What Is an Executable Operational Specification?

An executable operational specification is a machine-readable description of an operational objective that can be evaluated against observed evidence.

At a minimum, it should answer questions like:

What are we trying to achieve?

What constraints must hold?

What evidence should be collected?

How do we determine whether the operation conforms?

For example:

operation: deploy-orders-service

target:
  service: orders
  version: 2026.09.19
  environment: production

constraints:
  minAvailableReplicas: 3
  maxErrorRate: 0.01
  maxP95LatencyMs: 400
  region: us-east-1

evidence:
  - deployedVersion
  - availableReplicas
  - errorRate
  - p95Latency
  - region

This is intentionally simple. The important part is not the YAML syntax.

The important part is that the specification defines success independently from the mechanism used to perform the deployment.

That gives us a structure like:

Operational intent
        ↓
Specification
        ↓
Executor
        ↓
Execution
        ↓
Evidence
        ↓
Evaluation

The specification becomes a stable point of reference.

A Simple Deployment Example

Suppose we want to deploy version 2026.09.19 of an Orders service.

The operation succeeds only if:

the correct version is running
at least three replicas are available
error rate stays below 1%
p95 latency stays below 400 ms

We can express that as:

type DeploymentSpec = {
  service: string;
  version: string;
  minAvailableReplicas: number;
  maxErrorRate: number;
  maxP95LatencyMs: number;
};

For example:

const spec: DeploymentSpec = {
  service: "orders",
  version: "2026.09.19",
  minAvailableReplicas: 3,
  maxErrorRate: 0.01,
  maxP95LatencyMs: 400,
};

Now suppose execution produces evidence:

type DeploymentEvidence = {
  deployedVersion: string;
  availableReplicas: number;
  errorRate: number;
  p95LatencyMs: number;
};

For example:

const evidence: DeploymentEvidence = {
  deployedVersion: "2026.09.19",
  availableReplicas: 3,
  errorRate: 0.004,
  p95LatencyMs: 280,
};

We can evaluate the evidence against the specification:

function conforms(
  spec: DeploymentSpec,
  evidence: DeploymentEvidence
): boolean {
  return (
    evidence.deployedVersion ===
      spec.version &&
    evidence.availableReplicas >=
      spec.minAvailableReplicas &&
    evidence.errorRate <=
      spec.maxErrorRate &&
    evidence.p95LatencyMs <=
      spec.maxP95LatencyMs
  );
}

Then:

console.log(
  conforms(spec, evidence)
);

returns:

true

Now imagine the pipeline technically succeeds but only two replicas remain available:

const evidence: DeploymentEvidence = {
  deployedVersion: "2026.09.19",
  availableReplicas: 2,
  errorRate: 0.004,
  p95LatencyMs: 280,
};

The executor may still report success.

The specification does not:

conforms → false

That is the distinction we want.

Turn Success Criteria into Evidence Requirements

A specification becomes useful when its claims can be evaluated.

Suppose the specification says:

error rate must remain below 1%

Then the system needs evidence for:

error rate

If it says:

at least 3 replicas must remain available

then it needs evidence for:

available replica count

This sounds obvious, but it introduces an important discipline:

Every operational requirement should imply some form of observable evidence.

For example:

Requirement Evidence
correct version deployed running image/version
minimum replicas available replica count
error rate below threshold request/error metrics
latency below threshold latency metrics
correct region runtime placement
no schema regression schema validation result

This relationship matters because vague operational goals are difficult to automate safely.

Consider:

Deploy safely.

What evidence proves that?

The statement is too ambiguous.

A better specification decomposes "safely" into conditions that can be checked.

Why Observability Alone Is Not Enough

At this point you might ask:

Isn't this just observability?

Not exactly. Observability helps answer:

What is happening?

A specification helps answer:

What should be happening?

Those are complementary questions.

A dashboard might tell you:

error rate = 1.4%

That is an observation.

But whether 1.4% is acceptable depends on an expected condition.

The specification might say:

maxErrorRate = 1%

Now you can evaluate:

observed: 1.4%
expected: <= 1%

result: non-conformant

Without the expected condition, the metric is just a number. Without the metric, the specification cannot be verified. You need both.

Conceptually:

Specification
     +
Observed evidence
     ↓
Evaluation

Specifications Make Automation Verifiable

Automation without an independent specification is difficult to verify.

Consider a script that performs:

scale service
restart pods
change routing
wait
finish

If the script is also the only place where expected outcomes are encoded, then asking whether it behaved correctly becomes circular.

You are effectively asking:

Did the automation do what the automation says it should do?

A separate specification gives you another reference point.

Now you can ask:

What was intended?

What did the executor do?

What evidence did execution produce?

Did the evidence satisfy the specification?

This makes operations easier to audit and test. It also makes failures more informative.

Instead of:

deployment failed

you can potentially say:

deployment execution completed

but specification failed because:

availableReplicas:
expected >= 3
observed = 2

That is much more useful.

Keep the Specification Independent from the Executor

One of the strongest properties of this model is executor independence.

Suppose the specification says:

Deploy Orders version 2026.09.19

Keep:
- >= 3 replicas
- error rate <= 1%
- p95 latency <= 400 ms

One executor might use Kubernetes. Another might use a managed cloud platform. Another might use a custom orchestrator.

The specification should not need to change simply because the executor changed.

Conceptually:

                 ┌── Kubernetes Executor
Specification ───┼── Cloud Executor
                 ├── Custom Executor
                 └── AI Agent

Each executor produces evidence. Each execution is evaluated against the same intent.

That gives you a useful separation:

what should happen

from:

how it happens

This separation is common in other areas of software engineering. Interfaces separate callers from implementations. SQL separates queries from storage mechanics. Desired-state systems separate target state from reconciliation logic.

Operational specifications apply a similar idea to operational workflows.

A Minimal TypeScript Model

A simple generic model might look like this:

type Constraint<T> = {
  name: string;
  evaluate(
    evidence: T
  ): boolean;
};

type OperationalSpec<T> = {
  name: string;
  constraints: Constraint<T>[];
};

For deployment evidence:

type Evidence = {
  version: string;
  replicas: number;
  errorRate: number;
};

You can define:

const deploymentSpec:
  OperationalSpec<Evidence> = {
    name: "deploy-orders",
    constraints: [
      {
        name: "correct-version",
        evaluate: (evidence) =>
          evidence.version ===
          "2026.09.19",
      },
      {
        name: "minimum-replicas",
        evaluate: (evidence) =>
          evidence.replicas >= 3,
      },
      {
        name: "error-rate",
        evaluate: (evidence) =>
          evidence.errorRate <= 0.01,
      },
    ],
  };

Then evaluate every constraint:

function evaluate<T>(
  spec: OperationalSpec<T>,
  evidence: T
) {
  return spec.constraints.map(
    (constraint) => ({
      constraint: constraint.name,
      passed:
        constraint.evaluate(
          evidence
        ),
    })
  );
}

For:

const evidence: Evidence = {
  version: "2026.09.19",
  replicas: 2,
  errorRate: 0.003,
};

you might get:

correct-version    PASS
minimum-replicas   FAIL
error-rate         PASS

That is more useful than a single generic success or failure flag. It tells you exactly which part of the intended operation did not conform.

How This Applies to CI/CD

CI/CD systems already contain some declarative elements.

For example:

steps:
  - test
  - build
  - deploy

But these steps mostly describe execution order. A specification can add operational expectations around them.

For example:

Deployment objective:
release version X

Constraints:
tests passed
artifact digest matches approved build
minimum replicas remain available
error rate stays below threshold
rollback remains possible

The pipeline still performs the work. The specification defines the conditions the pipeline must satisfy. This also makes pipeline replacement easier.

If you move from:

GitHub Actions

to:

GitLab CI

or:

Argo

the executor changes.

The operational objective does not necessarily need to.

How This Applies to Infrastructure

Infrastructure-as-code already gives us desired state. That is closely related to this idea.

For example:

resource "aws_instance" "app" {
  instance_type = "t3.medium"
}

But operational intent often extends beyond configuration state.

You may also care about:

service availability
cost limits
regional restrictions
security controls
capacity
latency
backup freshness

Those constraints may live outside the IaC definition. An operational specification can bring them together.

For example:

Provision application environment

Required:
3 instances
region = us-east-1
monthly projected cost < $500
encryption enabled
backup age < 24h

The executor may use Terraform.

The evidence may come from:

cloud APIs
cost systems
security scanners
backup metadata

The specification gives those sources a common purpose.

How This Applies to Incident Response

Incident response is another place where execution and intent are often mixed together.

A runbook might say:

restart service
clear cache
scale replicas

But the actual operational objective might be:

restore checkout availability

while:
avoiding duplicate payments
preserving order state
keeping error rate below threshold

That difference matters.

If restarting the service does not restore checkout availability, the runbook technically executed but the operation failed.

An executable specification could express recovery conditions:

checkout success rate > 99%
payment duplication = 0
queue backlog < threshold
error rate < 1%

Then incident automation can be evaluated by the result it achieves, not just the actions it performs.

How This Applies to AI Agents

This becomes even more important with AI agents. Traditional automation usually follows predefined execution logic.

An AI agent may choose the execution path dynamically. For example, an operations agent might decide to:

inspect metrics
restart a service
change capacity
modify a feature flag
reroute traffic

The exact sequence may vary from one incident to another. That makes executor-level validation harder.

You cannot always verify the agent by checking whether it followed one exact script. But you can still verify operational intent.

For example:

Objective:
restore API availability

Constraints:
do not disable authentication
do not lose queued requests
error rate < 1%
p95 latency < 500 ms
cost increase < 20%

The agent may choose different actions and the specification remains stable.

That creates a useful control structure:

Human / organizational intent
        ↓
Operational specification
        ↓
Agent
        ↓
Actions
        ↓
Evidence
        ↓
Evaluation

The more autonomous execution becomes, the more valuable this separation becomes.

What Should Go Into an Operational Specification?

A useful specification often includes several categories.

Objective

What should be achieved?

For example:

Deploy Orders service version 2026.09.19

Scope

Where does the operation apply?

For example:

environment: production
region: us-east-1
service: orders

Constraints

What must remain true?

For example:

available replicas >= 3
error rate <= 1%
p95 latency <= 400 ms

Required Evidence

What must be observed?

For example:

running version
replica count
error rate
latency

Evaluation Rules

How do we decide whether execution conforms?

For example:

version must match exactly
replicas must be >= 3
error rate must be <= 0.01

Recovery Conditions

What should happen if conformance fails?

For example:

stop rollout
restore previous route
require human approval

Not every specification needs all of these.

But separating them makes operational intent much clearer.

What Should Stay Out of the Specification?

A specification should not become another implementation script. That means avoiding unnecessary executor-specific mechanics.

For example, this is probably too implementation-specific:

run kubectl command X
wait 10 seconds
call endpoint Y
run shell command Z

Those belong in an executor. The specification should focus on the desired operational outcome.

For example:

service version = 2026.09.19
available replicas >= 3
health checks passing

A useful rule is:

If changing the execution tool forces you to rewrite the specification, the specification may contain too much implementation detail.

Some executor-specific constraints are unavoidable. But the default should be to keep intent and mechanism separate.

A Practical Workflow

If I were introducing executable operational specifications into an existing system, I would start small.

1. Pick One Important Operation

For example:

deploy service
rotate certificate
restore backup
scale worker pool

2. Write Down the Objective

Ask:

What does success actually mean?

Not:

Which commands do we run?

3. Identify Constraints

For example:

minimum availability
maximum error rate
security requirements
regional restrictions
cost limits

4. Identify Evidence

For each constraint, ask:

What observation would prove or disprove this condition?

5. Separate the Executor

Keep the mechanism that performs the work independent from the specification.

6. Evaluate After Execution

Collect evidence and compare it against the specification.

7. Report Conformance

Prefer:

3 constraints passed
1 constraint failed

over:

operation failed

8. Improve the Specification

Missing evidence and ambiguous constraints will become visible quickly.

That is useful.

The specification becomes better as operational knowledge becomes explicit.

What Executable Specifications Do Not Solve

Executable specifications are not a complete operations architecture.

They do not automatically solve:

bad requirements
incorrect metrics
missing observability
distributed transactions
security failures
poor executor implementations
organizational ownership
conflicting business goals

They also introduce their own risks:

  • A bad specification can encode the wrong objective.

  • An incomplete specification can create false confidence.

  • A stale specification can become another source of drift.

  • And not every operational decision can be reduced to a simple threshold.

Human judgment still matters. The goal is not to eliminate judgment. The goal is to make operational intent more explicit and more testable.

From Automated Operations to Verifiable Operations

Software operations have spent years becoming more automated. That trend will continue. But increasing automation creates a new question:

How do we know the automation achieved the right outcome?

Execution logs, pipeline success, and agent confidence are not enough. We need something to compare execution against. That is where an executable operational specification becomes useful.

It gives us:

intent
↓
constraints
↓
evidence requirements
↓
execution
↓
observed evidence
↓
evaluation

That structure turns an operation from:

something happened

into:

something happened,
we know what was expected,
we collected evidence,
and we can evaluate the result.

That is a much stronger foundation for automation.

Conclusion

The more software operations we automate, the more important it becomes to separate what we want from how a tool executes it.

Pipelines are executors.

Infrastructure tools, scripts, and AI agents are executors. They can all perform actions.

But the operational objective should exist independently from the mechanism carrying it out.

An executable operational specification gives us a way to describe that objective in terms of:

desired outcome
constraints
required evidence
evaluation rules

Then execution becomes something we can verify instead of merely observe.

This matters today for deployments, infrastructure, and incident response.

It will matter even more as operational systems become increasingly autonomous.

Because automation can tell us that an action was executed.

What we really need to know is whether the system ended up where it was supposed to be.

]]> <![CDATA[ How to Migrate a Legacy Monolith Incrementally Without a Big-Bang Rewrite ]]> https://www.freecodecamp.org/news/migrate-legacy-monolith-incrementally/ 6aac7747d406d7c207351312 Thu, 17 Sep 2026 23:27:03 +0000 Large legacy migrations often fail long before the final cutover.

The failure usually starts when the migration is framed as a single event. Move the application. Move the database. Move all the users. Switch the traffic. Turn the old system off.

That creates a dangerous assumption: the legacy system and the new system need to exchange places all at once.

They usually don't.

If you already understand the legacy behavior, protect it with characterization tests, create migration-friendly boundaries, and compare old and new implementations, you have another option.

You can migrate one capability at a time. That changes the problem completely.

Instead of:

legacy monolith
      ↓
complete rewrite
      ↓
big-bang cutover

you can move toward:

legacy monolith
      ↓
one capability extracted
      ↓
small percentage of traffic
      ↓
observe
      ↓
expand
      ↓
repeat

The goal isn't to make the migration slower. The goal is to make each change smaller, observable, and reversible.

In this tutorial, I'll show you how to migrate a legacy monolith incrementally by:

  • choosing a safe first migration slice

  • defining a boundary between legacy and new code

  • routing requests between implementations

  • using the Strangler Fig pattern

  • migrating by business capability instead of technical layer

  • keeping old and new implementations running together

  • introducing progressive traffic

  • detecting failures before full cutover

  • designing rollback paths

  • handling data ownership carefully

  • removing migrated legacy behavior

  • using AI without turning an incremental migration into an automated rewrite

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

The objective is simple: make migration a sequence of controlled changes instead of one irreversible event.

Prerequisites

To follow along, you should be comfortable with:

  • TypeScript or a similar language

  • API and service boundaries

  • integration testing

  • dependency injection

  • routing and reverse proxies

  • database transactions

  • observability

  • incremental refactoring

  • legacy modernization

You should also already understand the behavior of the capability you want to migrate.

Ideally, you know:

  • its inputs

  • its outputs

  • its important business rules

  • its side effects

  • its dependencies

  • its external contracts

  • how you'll detect behavioral differences

If you haven't reached that point yet, migration may be premature.

Table of Contents

Why Big-Bang Migrations Are So Risky

Imagine a legacy commerce application.

It contains:

customers
orders
payments
inventory
shipping
invoicing
notifications
reporting

The modernization plan says:

replace the monolith

That sounds like one project.

Operationally, it may mean changing:

runtime
framework
database
deployment model
API contracts
authentication
networking
observability
data model
business logic
external integrations

at the same time.

If the final cutover fails, the number of possible causes is enormous.

For example:

Did pricing change?

Did the database migration lose data?

Is the payment provider failing?

Did authentication behave differently?

Did the new runtime change date handling?

Did a timeout become shorter?

Did an event stop being published?

Did the new deployment configuration fail?

This is one of the central problems with big-bang migration: too many variables change together.

Incremental migration tries to reduce the number of changing variables at each step.

Think in Migration Slices, Not Applications

Instead of asking:

How do we migrate this monolith?

ask:

What's the smallest meaningful business capability we can move independently?

For example:

Calculate Order Total
Generate Invoice
Send Order Confirmation
Create Shipment
Renew Subscription
Approve Customer

A migration slice should ideally have:

clear input
clear output
known side effects
understood dependencies
observable behavior
a rollback path

That gives you something concrete to move.

For example:

Generate Invoice

might become:

input:
orderId

behavior:
load order
calculate taxes
generate invoice number
create invoice

side effects:
store invoice
publish invoice.created

output:
invoice

That's much easier to migrate than:

billing module

or:

src/services/

Business capabilities make better migration units than folders.

Choose the First Capability Carefully

The first slice matters.

I would usually avoid starting with the most critical capability in the system.

You want something meaningful enough to validate the migration approach, but not so dangerous that a mistake creates catastrophic consequences.

A useful first slice often has:

moderate traffic
limited external dependencies
clear behavior
good test coverage
few transactional boundaries
low blast radius

For example:

Generate Customer Statement

may be a better first migration candidate than:

Authorize Payment

The first migration is partly technical work, but it's also a learning exercise.

You're validating:

routing
deployment
observability
rollback
data access
testing
team workflow

before applying the pattern to more critical capabilities.

Create a Boundary Between Legacy and New

Suppose the legacy application has:

async function generateInvoice(
  orderId: string
) {
  // legacy implementation
}

Before migration, introduce a boundary:

interface InvoiceGenerator {
  generate(
    orderId: string
  ): Promise<Invoice>;
}

The legacy implementation becomes:

class LegacyInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    orderId: string
  ): Promise<Invoice> {
    // existing behavior
  }
}

The new implementation becomes:

class NewInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    orderId: string
  ): Promise<Invoice> {
    // migrated behavior
  }
}

Now the caller doesn't need to know which implementation is active.

That creates an important capability:

replace implementation
without replacing caller

which is one of the foundations of incremental migration.

Use the Strangler Fig Pattern

A common way to describe incremental replacement is the Strangler Fig pattern.

Instead of replacing the entire application at once, new behavior gradually grows around the old system.

Conceptually:

            incoming request
                   │
                   ↓
                router
              /        \
             /          \
      legacy path     new path

At first:

legacy: 100%
new:      0%

Later:

legacy: 95%
new:      5%

Then:

legacy: 50%
new:     50%

Eventually:

legacy:  0%
new:    100%

At that point, the old implementation for that capability can be removed.

The key is that the replacement happens gradually. The legacy application continues serving parts of the system while the new implementation takes over others.

Migrate Capabilities, Not Technical Layers

One tempting migration strategy is:

move database
then move services
then move APIs
then move UI

That can create long periods where every capability spans both old and new architecture.

For example:

new API
↓
legacy service
↓
new database
↓
legacy event publisher

This is sometimes unavoidable.

But whenever possible, I prefer vertical slices.

A vertical slice might be:

Generate Invoice

request
↓
application logic
↓
persistence
↓
events
↓
response

That capability can move as one coherent unit.

Then:

Create Shipment

can move separately.

Then:

Renew Subscription

and so on.

This gives you working migrated capabilities earlier. It also reduces the number of temporary cross-system dependencies.

Keep Legacy and New Implementations Running Together

During an incremental migration, coexistence is normal.

For some period of time, you may have:

LegacyInvoiceGenerator
NewInvoiceGenerator

both deployed.

That's not duplication by accident. It's part of the migration strategy.

The important question is how requests choose between them.

You may use:

feature flag
tenant
user group
request header
region
percentage rollout
specific account IDs

For example:

class InvoiceRouter {
  constructor(
    private readonly legacy:
      InvoiceGenerator,
    private readonly migrated:
      InvoiceGenerator
  ) {}

  async generate(
    orderId: string,
    useMigrated: boolean
  ) {
    if (useMigrated) {
      return this.migrated.generate(
        orderId
      );
    }

    return this.legacy.generate(
      orderId
    );
  }
}

This is deliberately simple. The important part is that routing is explicit. You know which implementation handled each request.

Route Traffic Explicitly

Avoid migration logic that's difficult to observe.

For example:

try {
  return await newService.call();
} catch {
  return legacyService.call();
}

This may look resilient, but it can hide failures.

Suppose the new implementation fails 40% of the time. If every failure silently falls back to legacy, users may see no problem. But the migration isn't healthy.

The problem is that the first version mixes two decisions together: which implementation should receive the request and what should happen when that implementation fails. Because the fallback happens inside the catch, the migrated path can fail repeatedly without producing an explicit routing signal that you can measure.

A better approach is to make the routing decision first, record it, and then call the selected implementation. That separates migration policy from error handling and gives you a clear record of how much traffic actually reached each path.

For example:

const route =
  migrationPolicy.route(request);

metrics.increment(
  `invoice.route.${route}`
);

if (route === "migrated") {
  return migrated.generate(
    request.orderId
  );
}

return legacy.generate(
  request.orderId
);

Now you can measure:

requests routed to legacy
requests routed to migrated
migration failures
fallback count
latency
business outcomes

Migration should be observable as a first-class system behavior.

Start with Internal or Low-Risk Traffic

Before routing a large percentage of customers to the migrated path, start with safer traffic.

For example:

development
test environments
internal users
staff accounts
test tenants
specific low-risk customers

This lets you validate:

deployment
routing
observability
data access
external integrations
failure handling

with lower risk.

You can then expand.

For example:

internal users
↓
1% production
↓
5%
↓
10%
↓
25%
↓
50%
↓
100%

The exact percentages aren't important, but the principle is.

Each increase should happen because the previous stage produced enough evidence.

Progressively Increase Production Traffic

Suppose you have:

10,000 invoice requests/day

Instead of switching all requests:

legacy → new

at once, route:

1%

first.

That gives roughly:

100 real requests/day

through the migrated path.

Now monitor:

error rate
latency
output differences
side effects
customer-visible failures
business metrics

If the system behaves correctly, increase traffic. If it doesn't, reduce or disable migrated routing.

The migration becomes a controlled experiment. That's very different from a cutover event.

Use Differential Testing Before and During Rollout

The previous article in this series focused on differential testing. That technique becomes especially useful here.

Differential testing means running the legacy and migrated implementations with the same input and comparing their observable behavior. Depending on the capability, that may include return values, errors, state changes, and side effects.

The goal isn't to prove that the implementations are internally identical. It's to detect meaningful behavioral differences before those differences reach all of your production traffic.

Before live routing, you can compare:

same input
↓
legacy result

same input
↓
new result

During rollout, you can also sample real traffic and compare behavior where it is safe to do so.

For example:

real request
      │
      ├────→ active implementation
      │
      └────→ shadow implementation

Then compare:

output
errors
side effects
business state

This gives you evidence before increasing traffic.

A rollout decision can then be based on:

divergence
error rate
latency
business outcomes

instead of:

It seems fine.

A Small End-to-End Invoice Migration Example

The individual pieces are easier to understand when you see them working together.

Here's a deliberately small, in-memory example based on the invoice capability we've been using throughout the article. It doesn't include a real database, reverse proxy, queue, or deployment platform. The point is to show the migration control flow in one place.

Start with a shared contract:

type InvoiceInput = {
  orderId: string;
  subtotal: number;
};

type Invoice = {
  orderId: string;
  total: number;
};

interface InvoiceGenerator {
  generate(
    input: InvoiceInput
  ): Promise<Invoice>;
}

The legacy implementation calculates the invoice total like this:

class LegacyInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    return {
      orderId: input.orderId,
      total: input.subtotal * 1.21,
    };
  }
}

Now imagine we've migrated that capability into a new implementation:

class MigratedInvoiceGenerator
  implements InvoiceGenerator {
  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    const tax =
      input.subtotal * 0.21;

    return {
      orderId: input.orderId,
      total: input.subtotal + tax,
    };
  }
}

The code is different, but the intended behavior is the same.

Next, define a deterministic rollout function. This example assigns each orderId to a bucket from 0 to 99 so the same order always follows the same route:

function bucketFor(
  value: string
): number {
  const sum = [...value].reduce(
    (total, char) =>
      total + char.charCodeAt(0),
    0
  );

  return sum % 100;
}

function shouldUseMigrated(
  orderId: string,
  percentage: number
): boolean {
  return (
    bucketFor(orderId) < percentage
  );
}

If percentage is 10, roughly 10% of IDs will be assigned to the migrated path.

Now add some tiny in-memory metrics:

const metrics = {
  legacyRequests: 0,
  migratedRequests: 0,
  mismatches: 0,
};

Then put the legacy and migrated implementations behind one migration-aware entry point:

class IncrementalInvoiceService {
  migratedEnabled = true;
  rolloutPercentage = 10;

  constructor(
    private readonly legacy:
      InvoiceGenerator,
    private readonly migrated:
      InvoiceGenerator
  ) {}

  async generate(
    input: InvoiceInput
  ): Promise<Invoice> {
    const legacyResult =
      await this.legacy.generate(
        structuredClone(input)
      );

    const migratedResult =
      await this.migrated.generate(
        structuredClone(input)
      );

    if (
      migratedResult.orderId !==
        legacyResult.orderId ||
      migratedResult.total !==
        legacyResult.total
    ) {
      metrics.mismatches += 1;
    }

    const useMigrated =
      this.migratedEnabled &&
      shouldUseMigrated(
        input.orderId,
        this.rolloutPercentage
      );

    if (useMigrated) {
      metrics.migratedRequests += 1;
      return migratedResult;
    }

    metrics.legacyRequests += 1;
    return legacyResult;
  }
}

This small service combines several ideas from the article.

First, it runs both implementations with the same input and compares their results. Because this example is entirely in memory and has no external side effects, doing that is safe.

Second, it routes only a percentage of requests to the migrated result.

Third, it records how many requests used each path and how many behavioral mismatches occurred.

You can exercise it with a few requests:

const service =
  new IncrementalInvoiceService(
    new LegacyInvoiceGenerator(),
    new MigratedInvoiceGenerator()
  );

for (let i = 1; i <= 100; i++) {
  await service.generate({
    orderId: `order-${i}`,
    subtotal: 1000,
  });
}

console.log(metrics);

You might see something like:

legacyRequests:   89
migratedRequests: 11
mismatches:        0

The exact split may not be exactly 90/10 with only 100 inputs because the bucket function is intentionally simple. The important point is that routing is deterministic, measurable, and controlled by rolloutPercentage.

If the migrated implementation starts producing differences, the mismatch counter gives you an observable signal.

And if you decide the rollout should stop, rollback is explicit:

service.migratedEnabled = false;

From that point forward, all returned responses come from the legacy implementation again.

This is intentionally a simplified example. A production system would need stronger routing, real metrics, error handling, persistent state, and careful treatment of side effects.

In particular, you shouldn't blindly execute both implementations if generating an invoice sends email, writes to two production databases, charges a customer, or publishes externally visible events. In those cases, the shadow path needs recording adapters, isolated infrastructure, or another mechanism that lets you compare behavior without duplicating real effects.

But the control loop is the same:

same input
↓
compare legacy and migrated behavior
↓
route a small percentage
↓
observe
↓
expand or roll back

That is incremental migration in its smallest useful form.

Design Rollback Before You Need It

Rollback shouldn't be invented during an incident. Before moving traffic, ask what happens if the migrated path fails.

For routing-level migrations, rollback may be simple:

migration flag = false

and traffic returns to:

legacy implementation

For example:

if (
  featureFlags.useNewInvoices
) {
  return migrated.generate(
    orderId
  );
}

return legacy.generate(orderId);

If the migrated path behaves incorrectly:

useNewInvoices = false

Rollback is almost immediate.

But rollback becomes more complicated when:

data format changes
new data is written
events differ
external systems are updated
legacy code cannot read new records

In those cases, rollback may require more than flipping a feature flag. You might need backward-compatible schemas so both versions can read the same records, compensating actions for external side effects, replayable events, reconciliation jobs, or a short period where the legacy system remains able to consume data written by the new path.

For higher-risk migrations, it can also help to define a rollback boundary in advance. For example: traffic can return to legacy until a new schema version is written, or after a particular external event is emitted, recovery requires compensation instead of a simple rollback. The important part is knowing when rollback is still reversible and when you've crossed into a different recovery strategy.

That's why rollback design needs to happen before deployment.

Treat Data Migration as a Separate Problem

Application migration and data migration are related, but they aren't the same problem.

Suppose the legacy system stores:

{
  "customer_type": "P",
  "status": 2
}

while the new system stores:

{
  "customerType": "PREMIUM",
  "status": "APPROVED"
}

You now need to answer:

Which database is authoritative?

Can both systems read the same data?

Do we transform on read?

Do we migrate records in batches?

Do we replicate changes?

When does ownership change?

These decisions should be explicit. Otherwise the application migration may appear successful while the data boundary remains ambiguous.

Be Careful with Dual Writes

One common transition strategy is:

write to legacy database
+
write to new database

This is called dual writing, and it looks simple.

For example:

await legacyOrders.save(order);
await newOrders.save(order);

But what happens if:

legacy write succeeds
new write fails

Now the two systems disagree.

Or:

legacy write fails
new write succeeds

Same problem.

Dual writes create a distributed consistency problem.

If you use them, you need to think about:

retries
idempotency
reconciliation
ordering
partial failure
monitoring

Sometimes a safer approach is:

single authoritative write
↓
change event
↓
replication

or a transactional outbox.

There's no universal solution. The important point is not to treat dual writing as a trivial migration technique.

Decide Who Owns the Data

During coexistence, data ownership can become confusing.

Imagine:

legacy system writes customers

new system writes invoices

both systems read orders

That may be perfectly reasonable, but it should be documented.

For each migrated capability, define:

system of record
write owner
readers
replication direction
consistency expectations

For example:

Invoices

Write owner:
new system

Source of truth:
new database

Legacy access:
read-only adapter

Replication:
new → legacy reporting store

Now the architecture has an explicit direction.

Without ownership rules, migrations often create permanent synchronization problems.

Observe Business Behavior, Not Just Infrastructure

During rollout, teams often monitor:

CPU
memory
latency
HTTP 500s
database connections

Those are important. But they're not enough.

Suppose:

HTTP 200 rate = 99.99%

while:

invoice totals are wrong

Infrastructure monitoring says:

healthy

But the business system is not healthy.

Migration observability should include domain signals.

For example:

orders processed
payments authorized
invoices generated
discount distribution
failed renewals
average invoice total
events published

If you know normal business behavior, unusual changes can expose migration defects that technical metrics miss.

Know When a Migration Slice Is Complete

A capability isn't fully migrated just because traffic reached 100%.

Before declaring it complete, I would verify:

100% traffic on new path
acceptable error rate
acceptable latency
behavioral differences resolved
side effects verified
data ownership established
rollback window completed
legacy callers removed
legacy writes stopped
observability in place

Then ask:

Is the legacy implementation still serving any purpose?

If not, remove it.

Leaving both implementations permanently active creates:

maintenance cost
confusion
duplicate bugs
unclear ownership
future migration debt

Incremental migration should eventually simplify the system, not permanently duplicate it.

Remove the Legacy Path

This step is often delayed.

Teams migrate traffic but leave the old path in place:

just in case

Months later:

nobody knows whether it is still used

Before deleting it, verify:

routing metrics show zero traffic
no callers depend on it
data dependencies are removed
rollback period is complete
operational documentation is updated

Then remove:

legacy implementation
legacy feature flags
legacy database access
unused integration code
temporary compatibility layers

Deletion is part of migration.

A migration that only adds new architecture without removing old architecture can increase complexity rather than reduce it.

How to Use AI During an Incremental Migration

AI can help with many parts of this process.

For example, it can inspect the legacy codebase and help answer:

Which modules implement this capability?

Which callers depend on it?

Which database tables does it touch?

Which external services does it call?

Which side effects occur?

Which feature flags already exist?

Which paths need adapters?

A useful prompt might be:

Analyze the Generate Invoice capability.

Identify:

1. entry points,
2. business rules,
3. persistence dependencies,
4. external integrations,
5. side effects,
6. callers,
7. data ownership,
8. possible migration seams.

Do not redesign the system.

Return evidence for each finding using file paths
and relevant code references.

AI can also help compare migration changes.

For example:

Compare the legacy and migrated implementations.

Identify possible behavioral differences in:

- return values,
- errors,
- side effects,
- persistence,
- event ordering,
- retries,
- idempotency,
- transaction boundaries.

Do not assume the new implementation is correct.

This is useful because migration involves a lot of repetitive analysis, and AI can accelerate that analysis.

Don't Let AI Turn the Migration into a Rewrite

There's a common failure mode.

You ask:

Help me migrate this legacy capability.

The model responds with:

new architecture
new domain model
new API
new event model
new database schema
new validation layer
new framework

At that point, you're no longer migrating one capability, you're redesigning it.

Sometimes redesign is necessary, but it should be intentional.

During incremental migration, I prefer prompts with explicit constraints.

For example:

Migrate this capability without intentionally changing
observable behavior.

Preserve:

- inputs,
- outputs,
- errors,
- side effects,
- ordering where relevant,
- transactional behavior.

Only introduce the minimum structural changes required
to run it in the target environment.

List any behavior you cannot preserve with confidence.

That keeps the transformation narrow.

AI should help reduce mechanical effort. It shouldn't silently expand project scope.

A Practical Incremental Migration Workflow

Here's the workflow I would use.

1. Understand the Capability

Identify:

inputs
outputs
rules
side effects
dependencies
unknowns

2. Characterize Existing Behavior

Protect important behavior with:

characterization tests
integration tests
contract tests

3. Refactor for Migration

Create:

seams
adapters
explicit dependencies
clear orchestration

without intentionally changing behavior.

4. Build the New Implementation

Implement the capability in the target environment. Keep its observable contract clear.

5. Differentially Test Old and New

Compare:

outputs
errors
side effects
business state

using representative cases.

6. Introduce Explicit Routing

Allow requests to choose:

legacy
or
migrated

through an observable migration policy.

7. Start with Safe Traffic

Use:

internal users
test tenants
selected customers

8. Increase Traffic Gradually

For example:

1%
5%
10%
25%
50%
100%

only when evidence supports the next stage.

9. Monitor Technical and Business Metrics

Observe both:

system health
business behavior

10. Keep Rollback Available

Make returning to the legacy path fast and understood.

11. Transfer Data Ownership

Explicitly define which system owns:

writes
reads
replication

12. Remove the Legacy Path

After the migration has stabilized:

delete old implementation
remove temporary routing
remove obsolete dependencies

Then choose the next capability.

What Incremental Migration Doesn't Solve

Incremental migration reduces risk, but it doesn't eliminate complexity.

You may still need to deal with:

distributed transactions
shared databases
old schemas
tight coupling
unsupported runtimes
poor test coverage
organizational ownership
regulatory constraints

There are also systems where partial migration is extremely difficult.

For example:

highly stateful systems
strongly coupled desktop applications
large transactional batch systems
systems with shared global state

Sometimes the migration boundary needs to be larger.

The principle remains the same:

Make the smallest reversible change that produces useful migration progress.

Incremental doesn't always mean tiny. It means controlled.

The Complete Legacy Modernization Workflow

This article closes the workflow we've been building throughout this series.

We started with a basic problem:

How do you modernize a legacy application without accidentally turning the project into a rewrite?

The first step was understanding.

Legacy system
↓
investigate
↓
map behavior and dependencies

Then characterization.

observed behavior
↓
tests
↓
behavioral safety net

Then refactoring.

entangled capability
↓
seams and boundaries
↓
migration-friendly structure

Then differential testing.

legacy implementation
        +
new implementation
        ↓
behavior comparison

And finally incremental migration.

Understand
↓
Characterize
↓
Refactor
↓
Migrate
↓
Compare
↓
Route
↓
Observe
↓
Expand
↓
Remove legacy

The sequence matters.

If you skip understanding, you may migrate the wrong behavior.

If you skip characterization, you may not notice behavioral changes.

If you skip refactoring, the migration boundary may remain too large.

If you skip comparison, differences remain hidden.

If you skip incremental rollout, you discover problems at full blast radius.

Each step reduces a different kind of uncertainty.

Conclusion

Modernizing a legacy application doesn't require replacing everything at once.

In many cases, the safer strategy is to create a path where old and new implementations can coexist temporarily.

Move one capability, then compare it.

Route a small amount of traffic and observe what happens.

Increase traffic when the evidence supports it, and roll back when it doesn't.

Transfer ownership explicitly, then remove the legacy path.

And repeat.

The full workflow becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate incrementally
↓
Compare behavior
↓
Progressively route traffic
↓
Observe
↓
Remove legacy

AI can make every stage faster.

It can help map code, identify dependencies, generate adapters, compare implementations, analyze failures, and inspect migration diffs.

But speed isn't the same as confidence.

The important decisions still require engineering judgment:

What behavior matters?

What can change?

What should remain compatible?

What is the migration boundary?

What evidence is enough?

When is rollback necessary?

When can the legacy path be removed?

Those aren't code-generation questions. They're migration decisions.

And that's the larger lesson behind this entire series.

AI makes it increasingly cheap to produce new code. But that doesn't make legacy modernization trivial. It makes the quality of the decisions around the code more important.

Because the safest migration is rarely the one that changes the most software. It's the one that lets you change the system while continuously knowing what changed, why it changed, and whether it's safe to keep going.

]]> <![CDATA[ How to Use Differential Testing During a Legacy Migration ]]> https://www.freecodecamp.org/news/differential-testing-legacy-migration/ 6aa8200e59dfce663a0e73bd Mon, 14 Sep 2026 16:25:50 +0000 The most dangerous moment in a legacy migration isn't necessarily when you start writing the new implementation. It's when the new implementation looks finished.

The code compiles, the tests pass, the architecture is cleaner, and the new service responds faster.

Then everybody starts asking the same question:

Can we switch traffic now?

That's where confidence becomes difficult.

A new implementation can pass its own test suite and still behave differently from the system it is replacing.

Maybe rounding changed, or null values are handled differently, or an error became a successful response.

Maybe records are sorted differently, or a side effect happens in a different order, or a business rule you never documented was lost during the migration.

This is why, during a legacy migration, I like having another source of evidence: run the old and new implementations with the same inputs and compare what they do.

That's the basic idea behind differential testing. Instead of asking only if the new system passes its tests, you also ask: given the same input, where does the new system behave differently from the old one?

Those differences become evidence.

Some are bugs, some are intentional improvements, some are harmless representation differences, and some reveal behavior nobody knew existed.

In this tutorial, I'll show you how to use differential testing during a legacy migration to:

  • Compare old and new implementations

  • Define what should be considered equivalent

  • Normalize outputs before comparing them

  • Handle timestamps and other nondeterministic values

  • Compare errors and side effects

  • Run differential tests automatically

  • Introduce tolerances where exact equality doesn't make sense

  • Analyze mismatches

  • Use shadow traffic in production safely

  • Use AI to classify divergences without letting it decide correctness

  • Determine when the new implementation is ready for cutover

The examples use TypeScript and Vitest, but the approach applies to most languages and migration strategies.

The goal isn't to prove that two implementations are internally identical. It's to obtain evidence that they are behaviorally equivalent where equivalence matters.

Prerequisites

To follow along here, you should be comfortable with:

  • TypeScript or a similar language

  • unit and integration testing

  • asynchronous code

  • API and service boundaries

  • legacy modernization

  • basic observability concepts

You should also already have some understanding of the capability being migrated.

Ideally, you know its inputs, outputs, important business rules, external contracts, side effects, and known areas of uncertainty.

Differential testing works best after you've already created a boundary around the capability you want to migrate.

Table of Contents

What Differential Testing Actually Tells You

Imagine that your legacy application calculates the final price of an order.

The legacy implementation looks like this:

type Order = {
  subtotal: number;
  customerType: "STANDARD" | "PREMIUM";
  country: string;
};

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

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

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

  return Math.max(total, 0);
}

During the migration, you create a new implementation:

function newCalculateTotal(order: Order): number {
  const premiumDiscount =
    order.customerType === "PREMIUM"
      ? order.subtotal * 0.1
      : 0;

  const countryAdjustment =
    order.country === "AR"
      ? 500
      : 0;

  return Math.max(
    order.subtotal -
      premiumDiscount -
      countryAdjustment,
    0
  );
}

The implementations look different. And that's fine. What matters is whether they produce equivalent behavior.

A simple differential test can run both:

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

describe("order total migration", () => {
  it("matches the legacy implementation", () => {
    const order: Order = {
      subtotal: 10000,
      customerType: "PREMIUM",
      country: "AR",
    };

    const legacy =
      legacyCalculateTotal(order);

    const migrated =
      newCalculateTotal(order);

    expect(migrated).toBe(legacy);
  });
});

For this input:

legacy → 8500
new    → 8500

Good. But one matching example proves very little.

The value comes from systematically asking:

same input
↓
legacy implementation ──→ result A

same input
↓
new implementation ─────→ result B

compare A and B

Every mismatch gives you something to investigate.

Start with One Observable Boundary

Don't begin by comparing entire applications. To start, choose one capability.

For example:

Calculate Order Total
Generate Invoice
Approve Customer
Renew Subscription
Calculate Commission
Create Shipment

Suppose the migration boundary is:

interface OrderProcessor {
  process(order: Order): Promise<ProcessedOrder>;
}

Now you have two implementations:

LegacyOrderProcessor

NewOrderProcessor

That is a useful differential boundary, because both receive the same conceptual input, and both produce the same conceptual output.

You can compare them without requiring their internal architecture to match.

That matters because migrations often change structure intentionally.

The legacy implementation might be:

controller
→ service
→ SQL
→ provider SDK

while the new implementation might be:

use case
→ repository
→ gateway
→ events

Differential testing shouldn't care. It should care about observable behavior.

Run the Legacy and New Implementations with the Same Input

Suppose both implementations expose:

interface OrderProcessor {
  process(order: Order): Promise<ProcessedOrder>;
}

You can create:

const legacyProcessor =
  new LegacyOrderProcessor();

const newProcessor =
  new NewOrderProcessor();

Then:

it("produces the same processed order", async () => {
  const input: Order = {
    id: "order-1",
    subtotal: 10000,
    customerType: "PREMIUM",
    country: "US",
  };

  const legacy =
    await legacyProcessor.process(
      structuredClone(input)
    );

  const migrated =
    await newProcessor.process(
      structuredClone(input)
    );

  expect(migrated).toEqual(legacy);
});

Notice the use of:

structuredClone(input)

That matters if either implementation mutates its input.

Without separate copies, the first execution could influence the second.

You want:

same initial state

not:

new implementation receives state modified by legacy implementation

That kind of contamination can create misleading results.

Don't Compare Raw Output Blindly

The first version of a differential test is often:

expect(newResult).toEqual(legacyResult);

Sometimes that's exactly right. But other times it's wrong.

Imagine the legacy system returns:

{
  "id": "order-1",
  "total": 9000,
  "status": "PROCESSED",
  "generatedAt": "2026-09-09T10:00:01.231Z",
  "requestId": "legacy-f93a"
}

The new system returns:

{
  "requestId": "new-b517",
  "status": "PROCESSED",
  "generatedAt": "2026-09-09T10:00:01.416Z",
  "total": 9000,
  "id": "order-1"
}

A raw object comparison may fail because:

requestId differs
timestamp differs

But the business behavior might be equivalent.

You need to decide which fields are part of the meaningful contract.

Maybe:

id
total
status

matter.

While:

generatedAt
requestId

don't need exact equivalence.

That leads to normalization.

Normalize Values Before Comparing Them

Normalization means transforming outputs into a common representation before comparing them.

The goal isn't to change the business meaning of the data. It's to remove differences that are expected and irrelevant to the comparison, such as generated request IDs or timestamps, so the test can focus on the fields that actually define the behavior you care about.

In practice, that often means creating a canonical representation: a smaller, stable shape that contains only the meaningful fields you want to compare.

For example:

type ProcessedOrder = {
  id: string;
  total: number;
  status: string;
  generatedAt: string;
  requestId: string;
};

function normalizeOrder(
  order: ProcessedOrder
) {
  return {
    id: order.id,
    total: order.total,
    status: order.status,
  };
}

Here, ProcessedOrder contains both business-relevant fields and values that may legitimately differ between executions.

The normalizeOrder() function keeps id, total, and status, while leaving out generatedAt and requestId. That means two results can still be considered equivalent even if they were generated at slightly different times or used different request identifiers.

Now compare:

expect(
  normalizeOrder(migrated)
).toEqual(
  normalizeOrder(legacy)
);

This makes your equivalence rule explicit.

You're saying:

These fields define relevant behavior for this comparison.

Normalization can also handle:

  • ordering

  • casing

  • optional fields

  • timestamps

  • generated identifiers

  • numeric formatting

  • provider-specific metadata

But normalization must be deliberate. If you remove too much, you can hide real migration bugs.

Handle Timestamps and Other Nondeterministic Values

Legacy systems contain many nondeterministic values.

For example:

timestamps
UUIDs
random tokens
request IDs
trace IDs
database-generated IDs
unordered collections
provider-generated references

If you compare those values exactly, your differential suite may fail constantly.

One option is dependency control.

Dependency control means moving a nondeterministic source, such as the current time or an ID generator, behind an interface that you can replace during tests.

Instead of letting each implementation read the real clock independently, you inject the same controlled clock into both. That gives them the same value and removes time itself as a source of meaningless divergence.

Suppose the code uses:

new Date()

You can replace that dependency with a clock:

interface Clock {
  now(): Date;
}

Then both implementations receive:

const clock = {
  now: () =>
    new Date(
      "2026-09-09T10:00:00.000Z"
    ),
};

Now time becomes deterministic.

The same technique can work for ID generation:

interface IdGenerator {
  next(): string;
}

Then tests can provide:

const ids = {
  next: () => "fixed-id",
};

If controlling nondeterminism is impractical, normalize it out only when it's not part of the behavior you need to protect.

Compare Business Meaning, Not Just JSON

Two systems can return different representations while expressing the same business state.

Imagine you have this in your legacy system:

{
  "status": 2
}

And this in your new one:

{
  "status": "APPROVED"
}

Raw comparison says:

different

Business comparison may say:

equivalent

You can create a semantic normalizer:

function normalizeStatus(
  status: number | string
) {
  if (status === 2) {
    return "APPROVED";
  }

  return status;
}

Here, the normalizer translates the legacy numeric value 2 into the business meaning used by the new implementation: "APPROVED".

It doesn't claim that every number and string are interchangeable. It encodes one explicit equivalence rule that you've already decided is valid for this migration.

Then:

expect(
  normalizeStatus(newResult.status)
).toBe(
  normalizeStatus(legacyResult.status)
);

This is especially useful when migration intentionally changes:

database schema
API representation
enumerations
provider-specific formats
internal identifiers

The important question becomes:

Does the observable business meaning remain equivalent?

Not:

Are the bytes identical?

Compare Errors as Part of the Contract

Success responses aren't the whole behavior. Errors matter too.

Suppose the legacy implementation rejects a missing customer:

throw new Error("Customer not found");

The new implementation accidentally returns:

return null;

These two implementations behave very differently for the same invalid input.

The legacy version fails explicitly, while the new version silently returns a value that a caller may interpret as a successful result.

If your differential tests only exercise cases where a valid customer exists, both implementations may appear equivalent and this contract change will remain invisible.

That's why failure behavior has to be compared too.

Create cases that capture errors:

async function captureResult<T>(
  operation: () => Promise<T>
) {
  try {
    return {
      type: "success" as const,
      value: await operation(),
    };
  } catch (error) {
    return {
      type: "error" as const,
      error:
        error instanceof Error
          ? error.message
          : String(error),
    };
  }
}

The helper wraps an asynchronous operation and converts both possible outcomes into data.

If the operation succeeds, it returns an object with type: "success" and the returned value. If the operation throws, the catch block converts that exception into an object with type: "error" and a readable error message.

This gives both implementations the same comparison shape, so the test can compare success versus failure explicitly instead of letting an exception stop the test before the two behaviors can be evaluated.

Now:

const legacy =
  await captureResult(() =>
    legacyProcessor.process(input)
  );

const migrated =
  await captureResult(() =>
    newProcessor.process(input)
  );

expect(migrated.type).toBe(legacy.type);

If errors are contractually important, compare:

error category
HTTP status
error code
retryability
validation details

Don't necessarily compare exact wording unless clients depend on it.

Compare Side Effects, Too

One of the easiest migration mistakes is preserving the return value while losing a side effect.

Suppose both implementations return:

{
  "status": "PROCESSED"
}

But the legacy version also:

persists the order
publishes an event
creates a payment
writes an audit entry

and the new version forgets the audit entry.

Response-level differential testing won't catch that. So you'll want to capture side effects.

For example:

type Effect =
  | {
      type: "payment";
      orderId: string;
      amount: number;
    }
  | {
      type: "event";
      name: string;
      orderId: string;
    };

A test adapter can record them:

class RecordingPaymentGateway {
  effects: Effect[] = [];

  async charge(
    orderId: string,
    amount: number
  ) {
    this.effects.push({
      type: "payment",
      orderId,
      amount,
    });
  }
}

Instead of sending a real payment request, this adapter records what the application attempted to do in the effects array.

You can apply the same idea to event publication:

class RecordingEvents {
  effects: Effect[] = [];

  async publish(
    name: string,
    orderId: string
  ) {
    this.effects.push({
      type: "event",
      name,
      orderId,
    });
  }
}

The application still calls its payment and event dependencies as usual. The test doubles simply capture those calls as structured data instead of performing the real external actions.

After running the legacy and migrated implementations with their own recording adapters, you can compare the two recorded effect lists and verify that both systems attempted the same observable side effects.

Now the differential test can compare:

expect(newEffects).toEqual(legacyEffects);

Again, exact ordering should only be required if ordering matters.

Use Tolerances When Exact Equality Is Wrong

Some domains shouldn't use exact equality.

Imagine a migrated calculation produces:

legacy → 34.333333333
new    → 34.333333334

Is that a migration bug? Maybe not.

Floating-point calculations may justify a tolerance.

For example:

expect(newResult).toBeCloseTo(
  legacyResult,
  6
);

Or define an explicit comparator:

function withinTolerance(
  a: number,
  b: number,
  tolerance: number
) {
  return Math.abs(a - b) <= tolerance;
}

Then:

expect(
  withinTolerance(
    migrated.total,
    legacy.total,
    0.01
  )
).toBe(true);

But tolerances should come from domain requirements. Don't use them just to make failing tests disappear.

For financial systems, one cent can matter. For scientific calculations, a much smaller numerical difference may matter.

Equivalence is a business and engineering decision.

Build a Reusable Differential Test Harness

Once you compare more than a few cases, you can create a reusable harness.

For example:

type DifferentialResult<T> = {
  input: T;
  equivalent: boolean;
  legacy: unknown;
  migrated: unknown;
};

async function compareImplementations<
  TInput,
  TOutput
>(
  input: TInput,
  legacy: (
    input: TInput
  ) => Promise<TOutput>,
  migrated: (
    input: TInput
  ) => Promise<TOutput>,
  normalize: (
    output: TOutput
  ) => unknown
): Promise<
  DifferentialResult<TInput>
> {
  const legacyResult =
    await legacy(
      structuredClone(input)
    );

  const migratedResult =
    await migrated(
      structuredClone(input)
    );

  const normalizedLegacy =
    normalize(legacyResult);

  const normalizedMigrated =
    normalize(migratedResult);

  return {
    input,
    equivalent:
      JSON.stringify(
        normalizedLegacy
      ) ===
      JSON.stringify(
        normalizedMigrated
      ),
    legacy: normalizedLegacy,
    migrated: normalizedMigrated,
  };
}

The harness does four things.

First, it runs the legacy and migrated implementations with separate clones of the same input, so one execution can't mutate the data seen by the other.

Second, it passes both outputs through the same normalize() function. That applies the equivalence rules in one place instead of repeating them in every test.

Third, it compares the normalized results and records whether they're equivalent.

Finally, it returns the input and both normalized outputs together. That makes a failed comparison easier to inspect because the test report can show exactly which case diverged and what each implementation produced.

Then:

const result =
  await compareImplementations(
    input,
    legacyProcessor.process.bind(
      legacyProcessor
    ),
    newProcessor.process.bind(
      newProcessor
    ),
    normalizeOrder
  );

expect(result.equivalent).toBe(true);

For real systems, I would usually avoid relying on JSON.stringify() as the final equality mechanism.

The example keeps the harness readable.

In production-quality tooling, use a proper structural or domain-specific comparator.

The important part is that comparison logic becomes centralized.

Generate Test Cases from Real Behavior

Hand-written examples are useful. But migrations often fail on cases nobody thought to write manually.

Useful sources of inputs include:

existing test fixtures
historical incidents
production-safe request samples
database records
boundary values
previous bug reports
known customer scenarios

Suppose production shows these order shapes:

const cases: Order[] = [
  {
    subtotal: 0,
    customerType: "STANDARD",
    country: "US",
  },
  {
    subtotal: 500,
    customerType: "PREMIUM",
    country: "AR",
  },
  {
    subtotal: 10000,
    customerType: "STANDARD",
    country: "AR",
  },
];

The first block is the test data. It captures a small set of representative input shapes that you've observed in real usage or reconstructed safely from production behavior.

The next block is the test itself. it.each(cases) tells Vitest to run the same differential comparison once for every input in that array.

That separates two concerns: defining realistic cases and defining how every case should be evaluated.

Now:

it.each(cases)(
  "matches legacy behavior",
  async (input) => {
    const legacy =
      await legacyProcessor.process(
        structuredClone(input)
      );

    const migrated =
      await newProcessor.process(
        structuredClone(input)
      );

    expect(
      normalizeOrder(migrated)
    ).toEqual(
      normalizeOrder(legacy)
    );
  }
);

Real examples help expose assumptions that synthetic test data often misses. But production data must be handled carefully.

Remove or anonymize:

personal data
credentials
tokens
financial identifiers
confidential business data

The objective is to preserve useful behavioral shapes, not copy sensitive production information into test fixtures.

Classify Every Difference

A differential failure doesn't automatically mean that the new implementation is wrong.

Suppose you find 200 mismatches. Classify them.

I like categories such as:

migration defect
legacy defect intentionally preserved
intentional behavior change
representation difference
nondeterministic difference
test/comparator defect
unknown

For example:

Input:
subtotal = 5000

Legacy:
discount = 0

New:
discount = 500

Classification:
unknown

Investigation reveals that the new implementation changed:

amount > 5000

to:

amount >= 5000

Now you need a decision.

Was that:

accidental migration change

or:

intentional bug fix

Differential testing exposes the decision. It doesn't make the decision for you.

That's one of its greatest benefits.

How to Use AI to Investigate Differential Failures

Large migrations can produce hundreds or thousands of differences. And AI can help triage them.

Suppose you have:

{
  "input": {
    "subtotal": 5000,
    "country": "AR"
  },
  "legacy": {
    "total": 4500
  },
  "new": {
    "total": 4000
  }
}

You can give the model:

  • the input

  • both outputs

  • relevant legacy code

  • relevant migrated code

  • the comparator rules

Then ask:

Analyze this differential test failure.

Identify the smallest behavioral difference that could
explain the mismatch.

Compare the legacy and migrated implementations.

Return:

1. observed difference,
2. relevant legacy branch,
3. relevant migrated branch,
4. likely cause,
5. evidence supporting the cause,
6. additional test cases that could confirm it.

Do not decide which behavior is correct.
Do not modify the code yet.

That last instruction matters. AI can be very useful for locating why two implementations diverge. It shouldn't silently turn that diagnosis into a business decision.

Don't Let AI Decide Which Behavior Is Correct

Imagine the legacy system does this:

Customer age 65 → no discount
Customer age 66 → discount

The new system does:

Customer age 65 → discount
Customer age 66 → discount

AI may look at the code and say:

The new implementation appears more logical because senior discounts typically begin at age 65.

That's irrelevant.

The business rule might be:

age > 65

for a reason. Or the legacy behavior might contain a bug.

You need evidence.

Use:

requirements
existing tests
production behavior
business owners
historical tickets
commit history
contracts

AI can help gather and summarize that evidence. It shouldn't invent the rule.

Differential testing is valuable because it tells you that there's a difference before you accidentally turn that difference into production behavior.

How to Use Shadow Traffic Safely

Once offline differential tests look good, you can sometimes compare behavior with real traffic. This is often called shadowing or traffic mirroring.

The pattern looks like:

real request
    │
    ├────────────→ legacy system
    │                  │
    │                  ↓
    │             real response
    │
    └────────────→ new system
                       │
                       ↓
                  shadow result

The user still receives:

legacy response

while the new system processes a copy of the request.

Then you compare:

legacy output
vs.
shadow output

This can reveal cases that your test suite never captured.

For example:

unexpected null combinations
rare customer states
unusual international data
old records
large values
unusual sequence patterns

But shadow execution requires careful design, especially when the operation has side effects.

How to Prevent Shadow Execution from Duplicating Side Effects

Imagine shadowing:

POST /payments

If both systems really execute the payment, you have a serious problem.

The same applies to:

send email
create shipment
charge card
modify inventory
publish event
write external record

The shadow implementation shouldn't perform destructive or externally visible effects unless they're safely isolated.

One approach is to replace real gateways with recording adapters:

class ShadowPaymentGateway
  implements PaymentGateway {
  calls: PaymentRequest[] = [];

  async charge(
    request: PaymentRequest
  ) {
    this.calls.push(request);

    return {
      paymentId: "shadow",
    };
  }
}

The new implementation still tries to execute:

payment

but instead of charging a real card, the shadow adapter records:

what would have been sent

You can then compare that intent with the legacy side effect.

This distinction is important:

compare behavior

does not mean:

duplicate production effects

Measure Divergence Instead of Waiting for Perfection

When running thousands of comparisons, a binary:

pass / fail

may not tell the whole story.

You can measure divergence.

For example:

Requests compared:     100,000
Equivalent:             99,620
Different:                 380

Divergence rate:          0.38%

Then classify those 380:

250 timestamp differences
80 known intentional changes
30 comparator problems
15 migration defects fixed
5 still unexplained

After normalization:

meaningful unresolved divergence:
5 / 100,000
= 0.005%

Now the conversation becomes much more concrete.

Instead of:

I think the migration is ready.

you can say:

We compared 100,000 representative executions and have five unresolved behavioral differences.

Whether that's acceptable depends on what those five cases are.

One incorrect financial transaction can matter more than 100 harmless formatting differences.

So don't evaluate only the percentage. Evaluate the severity.

How to Know When You're Ready for Cutover

Differential testing doesn't give you a universal threshold. But it can give you evidence.

Before cutover, I would want to answer questions such as:

Have Important Input Classes Been Compared?

Not only happy paths.

Include:

boundaries
errors
historical bugs
large values
missing values
rare states

Are Meaningful Differences Classified?

Avoid:

we have 47 unexplained mismatches

Are Critical Differences Resolved?

Especially:

money
authorization
state transitions
data integrity
external contracts
idempotency

Are Intentional Differences Documented?

If the new behavior intentionally differs, that should be explicit.

Are Side Effects Equivalent?

Not only responses.

Have Production-like Cases Been Tested?

Synthetic fixtures alone may not be enough.

Can the Migration Be Rolled Back?

Differential confidence reduces risk. It doesn't eliminate the need for rollback.

If you can answer these questions, you're much closer to a controlled cutover.

A Practical Differential Testing Workflow

Here's the workflow I would use.

1. Pick One Capability

For example:

Process Order
Calculate Invoice
Approve Customer

Don't compare the whole platform at once.

2. Define the Observable Contract

List what matters:

return value
status
error
database state
events
external calls

3. Create Legacy and New Adapters

Expose both implementations through the same conceptual interface.

4. Define Normalization Rules

Decide how to handle:

timestamps
generated IDs
ordering
representation changes
optional values

Do this before looking at lots of failures. Otherwise you may weaken the comparator simply to make results pass.

5. Compare Known Cases

Begin with:

existing tests
characterization cases
edge cases
historical bugs

6. Capture Side Effects

Use recording or fake adapters where necessary.

7. Automate the Harness

Produce structured output for every mismatch.

For example:

{
  "caseId": "case-493",
  "equivalent": false,
  "legacy": {},
  "migrated": {},
  "difference": {}
}

8. Classify Differences

Use categories:

defect
intentional change
normalization issue
nondeterminism
unknown

9. Add Representative Real-World Cases

Use anonymized or safely reconstructed production patterns.

10. Shadow Real Traffic When Appropriate

Only after controlling side effects and privacy risk.

11. Measure Divergence

Track both:

frequency
severity

12. Resolve Unknowns Before Cutover

The most dangerous category is often not:

different

It is:

different and nobody knows why

What Differential Testing Can't Prove

Differential testing has an important limitation: it compares the new system against the old one.

That means the legacy system becomes a behavioral reference. But the legacy system may already be wrong.

Suppose:

legacy output = wrong
new output    = same wrong result

The differential test passes, but that doesn't make the behavior correct.

This is why differential testing should complement:

specification tests
characterization tests
business requirements
security testing
performance testing
contract testing
domain review

It answers:

Did behavior change?

It doesn't automatically answer:

Is this the right behavior?

That distinction matters. The legacy application is evidence, it's not absolute truth.

Differential Testing Turns Migration Risk into Evidence

There's another reason I like this technique. Without differential testing, migration discussions can become subjective.

One person says:

The new implementation looks ready.

Another says:

I do not trust it yet.

Both may have reasonable instincts, but neither statement is very measurable.

Differential testing changes the conversation.

Now you can say:

12,000 cases compared
47 differences found
31 representation differences
9 intentional behavior changes
6 migration defects fixed
1 unresolved

That is a much better engineering discussion. You're converting uncertainty into observable differences. Then you can decide what to do with them.

Conclusion

A legacy migration is not complete because the new implementation passes its own tests.

The harder question is whether it preserves the behavior that matters from the system it is replacing.

Differential testing gives you another way to answer that question.

Run both implementations with the same inputs.

Compare outputs.

Compare errors.

Compare side effects.

Normalize only the differences that truly do not matter.

Investigate everything else.

And when possible, use representative production behavior to discover cases your test suite did not anticipate.

The migration sequence now becomes:

Understand
↓
Characterize
↓
Refactor
↓
Migrate
↓
Compare
↓
Cut over

AI can accelerate this process too.

It can help build comparators, analyze failures, group similar divergences, inspect code paths, and suggest additional test cases.

But it should not decide which implementation is correct.

That still requires evidence, domain knowledge, and engineering judgment.

The purpose of differential testing is not to eliminate uncertainty completely.

It is to make uncertainty visible before you switch production traffic.

Because during a migration, discovering that the new system behaves differently is useful.

Discovering it after the old system has been turned off is much more expensive.

]]> <![CDATA[ How to Refactor a Legacy Application Before Migrating It ]]> https://www.freecodecamp.org/news/refactor-legacy-application-before-migration/ 6a9f3503813f6309fdfcd6e3 Mon, 07 Sep 2026 22:04:51 +0000 The moment a team decides to migrate a legacy application, there's usually pressure to start moving code.

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

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.

]]> <![CDATA[ How to Build Characterization Tests Before Refactoring Legacy Code ]]> https://www.freecodecamp.org/news/characterization-tests-before-refactoring-legacy-code/ 6a958d8401db3f18f07d0b54 Mon, 31 Aug 2026 14:19:48 +0000 The first thing many engineers want to do when they inherit legacy code is improve it.

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

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:

Behavior Evidence Protected?
Premium discount Code + production example No
Order event Code Yes
Transfer adjustment Code No
Negative total clamp Code No
Save status Existing integration test Yes

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.

]]> <![CDATA[ How to Understand a Legacy Codebase Using AI Before Changing it ]]> https://www.freecodecamp.org/news/understand-a-legacy-codebase-with-ai/ 6a888892029633fd14697876 Fri, 21 Aug 2026 17:19:14 +0000 The first thing many engineers want to do when they inherit a legacy codebase is change it. And I understand the impulse.

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

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.

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.

]]> <![CDATA[ How to Modernize a Legacy Application with AI Without Turning It Into a Rewrite ]]> https://www.freecodecamp.org/news/modernize-legacy-applications-with-ai/ 6a7e4a380ee61c58fa48acb3 Thu, 13 Aug 2026 22:50:32 +0000 I have seen legacy migrations considered successful because the old framework disappeared from the repository.

Six months later, the team was still dealing with the same coupling, the same unclear business rules, and almost the same deployment problems.

The technology had changed but the system hadn't changed very much as a whole.

AI makes this problem even more interesting.

It can translate code faster than a team could do manually. It can explain unfamiliar classes, generate tests, create adapters, update APIs, and remove a significant amount of repetitive work.

But if you point an AI coding tool at an old application and simply ask it to migrate everything to a modern stack, there's a good chance you'll get exactly what you asked for: the same system, rewritten faster.

That's not necessarily modernization.

In this tutorial, I want to show you a different way to use AI during a legacy migration.

Instead of treating AI as an automated code translator, you'll use it to help you:

  • understand an unfamiliar codebase,

  • identify business rules and hidden dependencies,

  • build a behavioral safety net,

  • find boundaries for incremental migration,

  • refactor before replacing,

  • automate repetitive transformations,

  • compare old and new behavior,

  • and detect regressions before they reach production.

The examples use TypeScript, but the process itself isn't tied to TypeScript or Node.js.

The important part is the workflow. AI can make migration work faster. But Engineering still has to decide what's worth migrating.

Prerequisites

You should be comfortable with:

  • basic TypeScript,

  • unit and integration testing,

  • dependency injection,

  • software architecture concepts,

  • and working with an existing codebase.

The examples use Vitest, but the same ideas apply if you use Jest or another testing framework.

Table of Contents

How to Avoid a One-to-One Legacy Migration

Imagine that you find this function in an old order-processing system:

async function processOrder(order: Order) {
  if (!order.customer.active) {
    throw new Error("Inactive customer");
  }

  const discount =
    order.customer.type === "PREMIUM"
      ? order.total * 0.1
      : 0;

  const finalAmount = order.total - discount;

  await db.orders.insert({
    customerId: order.customer.id,
    amount: finalAmount,
  });

  await paymentGateway.charge(
    order.customer.card,
    finalAmount,
  );

  await mailer.send(
    order.customer.email,
    "Order processed",
  );

  return finalAmount;
}

The function works, but it also does quite a lot.

It validates the customer, applies a pricing rule, persists data, charges a payment method, and sends a notification.

A one-to-one migration might turn this into a prettier TypeScript service with newer libraries while keeping all those responsibilities together.

You might replace an old controller with a new controller, an old service with a new service, and an old ORM with a new ORM...and still preserve the same architectural problem.

This is one of the first places where AI can work against you.

If your prompt is:

Convert this legacy class to TypeScript.

the model will normally preserve the structure because preserving the structure is the task you gave it.

Before asking AI to transform code, separate two questions:

  1. What behavior must survive?

  2. What design should survive?

Those aren't the same question.

Sometimes an implementation is old but its behavior is still essential. Sometimes the behavior matters but the implementation should disappear. And sometimes you discover that neither needs to survive.

That distinction should happen before the bulk migration begins.

How to Map a Legacy Codebase Before Changing It

The first difficult part of a legacy migration is usually understanding what you actually have.

Documentation helps when it exists. But in many systems, the real documentation is distributed across:

  • conditional statements,

  • database constraints,

  • scheduled jobs,

  • comments,

  • logs,

  • integration code,

  • tests,

  • configuration,

  • and knowledge that lives in people's heads.

This is an area where AI can save time without being asked to make architectural decisions.

Take the previous processOrder function. Instead of asking AI to rewrite it, start with questions such as:

Identify the business rules in this function.

List every side effect.

Which external systems does it depend on?

Which parts could be expressed as pure functions?

Which observable behaviors should probably be protected
with tests before this function is changed?

Do not rewrite the function.

The last instruction matters more than it may seem.

When analysis and transformation happen in the same request, it becomes easy for an AI tool to solve a design problem you haven't fully understood yet.

I prefer to make the analysis explicit first.

For a larger codebase, repeat the process at several levels.

At repository level, look for:

  • entry points,

  • database access,

  • external APIs,

  • message queues,

  • background jobs,

  • scheduled tasks,

  • configuration,

  • shared state,

  • authentication,

  • and authorization.

At module level, look for:

  • business rules,

  • dependencies,

  • side effects,

  • duplicated logic,

  • highly coupled classes,

  • and implicit contracts.

At function level, look for:

  • inputs,

  • outputs,

  • exceptions,

  • state changes,

  • external calls,

  • and edge cases.

AI can make this exploration much faster. But its findings should be checked against the actual repository, tests, schema, logs, and production behavior.

A confident explanation of the code is still only an explanation. The repository remains the source of truth.

How to Build Characterization Tests Before Refactoring

One of the uncomfortable parts of legacy software is that strange behavior is not necessarily accidental.

You may find code that looks obviously wrong and discover later that another part of the business depends on it.

This is where characterization tests are useful.

Michael Feathers discusses this approach in Working Effectively with Legacy Code: instead of beginning by describing how the system should behave, you first capture how it behaves today.

Consider this function:

export function calculateDiscount(
  customerType: string,
  total: number,
): number {
  if (customerType === "PREMIUM") {
    return total * 0.1;
  }

  return 0;
}

You can protect its current behavior with tests:

import { describe, expect, it } from "vitest";
import { calculateDiscount } from "./calculateDiscount";

describe("calculateDiscount", () => {
  it("applies a 10 percent discount to premium customers", () => {
    expect(
      calculateDiscount("PREMIUM", 100),
    ).toBe(10);
  });

  it("does not discount regular customers", () => {
    expect(
      calculateDiscount("REGULAR", 100),
    ).toBe(0);
  });

  it("returns zero when the order total is zero", () => {
    expect(
      calculateDiscount("PREMIUM", 0),
    ).toBe(0);
  });
});

AI is useful for expanding this safety net.

For example:

Generate characterization tests for this function.

Preserve the existing behavior.

Include:
- normal inputs,
- boundary values,
- invalid inputs,
- exceptions,
- observable side effects.

Do not redesign the function.

Then review what it generates.

You aren't proving that the old behavior is correct. You're recording what will change if you refactor it.

That difference matters.

If a test captures a behavior you later decide is a bug, change it intentionally. What you want to avoid is changing behavior accidentally and discovering the difference after deployment.

How to Find Safe Migration Seams

Legacy applications rarely need to be replaced all at once.

They usually need places where the old and new systems can coexist temporarily.

Feathers also describes the idea of a seam in Working Effectively with Legacy Code: a place where you can alter behavior without having to modify everything around it.

The order-processing example gives you one possible seam.

The original function contains:

  • customer validation,

  • discount calculation,

  • database persistence,

  • payment processing,

  • and email notification.

The first two belong naturally to business behavior. The others involve infrastructure. That suggests a possible boundary.

Domain/application responsibilities:

  • customer rules,

  • pricing rules,

  • order workflow.

Infrastructure responsibilities:

  • database,

  • payment provider,

  • email provider.

AI can help identify candidates for these boundaries.

For example:

Analyze these files and identify:

- business rules,
- infrastructure concerns,
- side effects,
- shared mutable state,
- duplicated logic,
- dependencies that make isolated testing difficult.

Suggest possible boundaries.

Do not rewrite the code yet.

Again, the AI output is input to an engineering decision. It shouldn't become the decision automatically.

When you find a good seam, you gain a place where modernization can progress without requiring a rewrite of the entire application.

How to Refactor Toward Explicit Responsibilities

Once you understand a section of the code and have tests around its current behavior, refactoring becomes less dangerous.

The pricing rule can become a pure function:

export function calculateDiscount(
  customerType: string,
  total: number,
): number {
  if (customerType === "PREMIUM") {
    return total * 0.1;
  }

  return 0;
}

Customer validation can be separated:

export function validateCustomer(
  customer: Customer,
): void {
  if (!customer.active) {
    throw new Error("Inactive customer");
  }
}

Infrastructure can move behind contracts:

export interface OrderRepository {
  save(order: PersistedOrder): Promise<void>;
}

export interface PaymentGateway {
  charge(
    card: string,
    amount: number,
  ): Promise<void>;
}

export interface NotificationService {
  sendOrderConfirmation(
    email: string,
  ): Promise<void>;
}

The application workflow becomes easier to read:

export class ProcessOrder {
  constructor(
    private readonly orders: OrderRepository,
    private readonly payments: PaymentGateway,
    private readonly notifications: NotificationService,
  ) {}

  async execute(order: Order): Promise<number> {
    validateCustomer(order.customer);

    const discount = calculateDiscount(
      order.customer.type,
      order.total,
    );

    const finalAmount =
      order.total - discount;

    await this.orders.save({
      customerId: order.customer.id,
      amount: finalAmount,
    });

    await this.payments.charge(
      order.customer.card,
      finalAmount,
    );

    await this.notifications.sendOrderConfirmation(
      order.customer.email,
    );

    return finalAmount;
  }
}

There's nothing particularly revolutionary in this refactoring. That's part of the point.

Modernization doesn't require an exotic architecture.

Often the important improvement is simply making responsibilities explicit enough that the next change doesn't require understanding the entire application.

How to Use AI for Mechanical Transformations

Once the boundaries are clear, AI becomes much more useful for implementation.

A surprising amount of migration work is necessary but repetitive:

  • translating APIs,

  • replacing framework conventions,

  • generating adapters,

  • converting configuration,

  • updating type definitions,

  • changing data access libraries,

  • and updating repetitive integration code.

These are good places to use AI.

Imagine that the old system performs SQL directly:

async function getCustomer(id: number) {
  const result = await db.query(
    `SELECT * FROM customer WHERE id = ${id}`,
  );

  return result[0];
}

Before generating the new implementation, define the contract you want:

export interface CustomerRepository {
  findById(id: number): Promise<Customer | null>;
}

Then constrain the transformation:

Implement CustomerRepository using the new database client.

Constraints:

- Keep the CustomerRepository interface unchanged.
- Use parameterized queries.
- Do not move business rules into the repository.
- Preserve the existing null behavior.
- Preserve the existing error semantics.
- Return only the implementation.

This is a very different request from:

Modernize this database code.

In the first case, you made the architectural decision and asked AI to implement within that boundary.

That is where I find AI most useful in migration work. It removes mechanical effort after the important decisions have already been made.

How to Migrate in Small Vertical Slices

Large migrations become difficult to reason about when thousands of files change together.

A safer unit of change is often a business capability.

Instead of migrating all controllers, then all services, and finally all repositories, migrate one complete capability.

For example:

Create Order

  • API

  • application logic

  • domain rules

  • persistence

  • tests

Then move to the next capability.

This has several advantages. First, the migration remains closer to deployable software. Second, the context you give an AI tool stays smaller.

Testing also becomes more focused. And if something goes wrong, the failure is easier to isolate.

A useful first prompt for a vertical slice is analysis-only:

We are migrating the Create Order capability.

The legacy implementation is under /legacy/orders.

The target architecture separates:
- domain,
- application,
- infrastructure.

The characterization tests under /tests/legacy
describe behavior that must remain compatible.

Analyze the current implementation.

List:
1. business rules,
2. external dependencies,
3. side effects,
4. likely migration risks,
5. files that need to change.

Do not generate code yet.

Review that output, then plan the actual transformation.

This is also compatible with an incremental replacement strategy such as Martin Fowler's Strangler Fig approach, where new functionality gradually takes over from an older system instead of requiring one large cutover.

The important word is gradually.

AI can increase transformation speed. That doesn't make a big-bang migration less risky.

How to Compare Legacy and Modern Behavior

Unit tests give you one kind of safety.

For a migration, I also like comparing the old and new implementations directly.

Suppose both systems can process the same order. You can run the same fixture through each one:

const inputs = [
  premiumCustomerOrder,
  standardCustomerOrder,
  inactiveCustomerOrder,
];

for (const input of inputs) {
  const legacyResult =
    await legacyProcessor(input);

  const modernResult =
    await modernProcessor(input);

  expect(modernResult).toEqual(legacyResult);
}

This is a simple form of differential testing. You can do the same thing at the HTTP boundary.

Send the same POST /orders request to both versions and compare:

  • status codes

  • response payloads

  • database changes

  • emitted events

  • external calls

  • errors

An important point: a difference isn't automatically a bug. Sometimes behavior is supposed to change. The useful thing is making the difference visible so someone has to classify it deliberately.

AI can help here too.

If you have hundreds of mismatches, you can ask it to group them:

Analyze these behavioral mismatches.

Group them by likely cause.

Pay particular attention to:
- rounding,
- null handling,
- timezone conversion,
- validation,
- serialization,
- data mapping.

Do not label a mismatch as a defect unless the
available evidence supports that conclusion.

This is a good use of AI because the model is reducing investigation work. It's not deciding whether production behavior is acceptable.

How to Use Shadow Traffic to Find Regressions

Eventually, test fixtures stop being representative enough.

Production systems receive combinations of inputs nobody thought to put into a test suite.

One way to observe those differences is shadow traffic. The legacy application continues serving the user's request, and a copy of that request also goes to the new implementation. The new result is used for comparison only and isn't returned to the user.

For example:

Legacy:
200
{ "total": 90 }

Modern:
200
{ "total": 90 }

MATCH

Or:

Legacy:
200
{ "total": 90 }

Modern:
200
{ "total": 100 }

MISMATCH

Collecting those mismatches gives you evidence about how the new system behaves under real traffic without immediately exposing users to it.

This technique comes with operational considerations. You need to think carefully about:

  • duplicated side effects,

  • payment calls,

  • emails,

  • writes,

  • privacy,

  • production load,

  • and external API usage.

A shadow instance should generally avoid performing irreversible side effects.

For example, replace the real payment adapter with a recording adapter:

export class RecordingPaymentGateway
  implements PaymentGateway {

  public readonly calls: Array<{
    card: string;
    amount: number;
  }> = [];

  async charge(
    card: string,
    amount: number,
  ): Promise<void> {
    this.calls.push({
      card,
      amount,
    });
  }
}

Now you can compare the intention to charge without charging a customer twice.

How to Test the Architecture You Actually Want

Behavioral compatibility isn't enough if one objective of the migration is improving the architecture.

Imagine that you've decided on this constraint:

Domain code must not depend on infrastructure code.

If that rule only exists in an architecture diagram, migration pressure will eventually break it.

So test it.

For a simple project, you can inspect imports. For a larger one, use a dependency-analysis tool capable of enforcing architectural rules.

The exact tooling matters less than the principle:

If an architectural constraint matters, make breaking it visible.

You may want rules such as:

  • domain must not depend on infrastructure

  • domain must not depend on the HTTP framework

  • application code must not depend directly on the database driver

  • modules must not import another module's internal implementation

Why does this matter in an AI-assisted migration? Because AI is very good at finding a way to make code compile.

If reaching directly into another module solves the immediate problem, generated code may do exactly that unless the boundary is part of the constraints.

Architecture tests give both humans and AI tooling a harder boundary to violate accidentally.

How to Decide Which Tasks AI Should Handle

I don't treat all migration tasks equally. Some are good candidates for automation.

Tasks Where AI Is Usually Useful

  • explaining unfamiliar code

  • identifying dependencies

  • extracting candidate business rules

  • generating characterization test cases

  • generating repetitive adapters

  • updating framework APIs

  • translating mechanical code

  • creating migration checklists

  • comparing implementations

  • classifying regression output

  • drafting technical documentation

Tasks Where I Want Significant Engineering Review

  • proposing module boundaries

  • extracting domain concepts

  • refactoring highly coupled classes

  • choosing migration sequences

  • changing data models

  • designing integration boundaries

Decisions I Would Keep Under Human Ownership

  • target architecture

  • acceptable behavioral differences

  • security boundaries

  • data migration strategy

  • rollout strategy

  • rollback strategy

  • removal of legacy behavior

  • production risk acceptance

This isn't because AI can't produce an architecture proposal. It can.

The problem is accountability and context.

Architecture choices are consequences of constraints, history, organizational capabilities, business priorities, and operational risks that may not exist anywhere in the repository.

A model can help you explore those choices, but someone still has to own them.

How to Measure Whether the Migration Actually Improved the System

Migration velocity is an attractive metric because it's easy to show.

For example:

37% of the codebase migrated.

That doesn't tell you much about whether the system became better.

A modernization effort should look at several kinds of outcomes. Operational metrics might include:

  • deployment frequency

  • change failure rate

  • mean time to recovery

  • production incidents

  • build time

Engineering metrics might include:

  • test coverage

  • high-complexity classes

  • duplicated business rules

  • cross-module dependencies

  • architectural violations

  • time required to change a capability

Migration-specific metrics might include:

  • regression rate

  • percentage of traffic handled by the new path

  • unresolved behavioral mismatches

  • rollback frequency

  • legacy components still in use

The exact metrics depend on the system. What matters is avoiding this definition of success:

Old repository is smaller = modernization succeeded.

AI makes it possible to transform more code in less time. That makes measuring the quality of the transformation more important, not less.

The Risk I Worry About Most with AI-Assisted Migration

Hallucinated code is a clear risk. But I worry more about plausible code.

Generated code can compile. It can look cleaner than the original implementation. It can even pass a shallow test suite. And it can still subtly change a business rule that nobody realized existed.

Consider something as small as:

if (customer.balance > 0) {
  charge(customer);
}

It's tempting to clean up code when you don't understand why a condition exists.

But maybe zero has a special business meaning.

Maybe negative balances are legitimate.

Maybe the condition was introduced after a production incident six years ago and never documented.

AI can't recover context that doesn't exist in the information available to it. This is why I put so much emphasis on characterization tests and behavioral comparison.

The faster the transformation becomes, the stronger the validation process needs to become.

Otherwise, you're only increasing the speed at which you can introduce unknown changes.

A Practical Migration Workflow

If I had to reduce the process to one repeatable sequence, I would use this.

1. Understand

Map:

  • behavior

  • dependencies

  • business rules

  • side effects

  • data

  • integrations

Use AI to accelerate the investigation. Don't start by generating the new system.

2. Protect

Build:

  • characterization tests

  • integration tests

  • API fixtures

  • behavioral snapshots

Make current behavior observable.

3. Design

Choose:

  • boundaries

  • interfaces

  • responsibilities

  • migration seams

Do this before large-scale transformation.

4. Refactor

Create enough separation that part of the system can move without dragging everything else with it.

5. Transform

Use AI heavily for repetitive implementation work.

Give it explicit architectural constraints.

6. Compare

Run old and new behavior against the same inputs and investigate differences.

7. Release Gradually

Use the mechanisms appropriate for your environment:

  • feature flags

  • canary deployments

  • shadow traffic

  • observability

  • rollback

8. Remove the Old Path

Don't leave both systems running indefinitely. A migration that never removes the legacy path eventually creates another legacy architecture.

Conclusion

AI changes the economics of legacy modernization.

A lot of work that used to consume engineering hours can now happen much faster: reading unfamiliar code, generating tests, updating APIs, translating repetitive implementations, and investigating differences between systems.

That's useful. But it's not the part of modernization that requires the most judgment.

The difficult questions remain:

  • What behavior still matters?

  • What should disappear?

  • Which dependencies should survive?

  • Where should the boundaries be?

  • How much behavioral change is acceptable?

  • When is the new implementation safe enough to receive production traffic?

If you use AI only to translate code, you can migrate technical debt faster.

If you combine it with characterization testing, incremental refactoring, explicit architectural boundaries, differential testing, and controlled rollout, you have a better chance of improving the system while you move it.

The objective isn't to move the same system onto a newer stack. It's to understand it, protect its important behavior, refactor it, migrate it incrementally, validate the result, and end up with a simpler system than the one you started with.

AI can shorten that path. But it still can't decide what the destination should be.

]]>