Using Claude for Legacy Code Migration Without Losing Behavior

Legacy migration is not a translation exercise. Old code often contains undocumented behavior, compatibility workarounds, operational assumptions, and data contracts that users depend on. Claude can accelerate inventory, test generation, dependency analysis, and mechanical conversion, but the migration must be governed by behavioral evidence.

Define the Migration Boundary

State the source and target environments, supported interfaces, performance requirements, rollout constraints, and explicit non-goals. Decide whether the objective is language migration, framework replacement, dependency upgrade, architecture change, or some combination. Combining all of them in one rewrite makes failures difficult to isolate.

Create a migration brief:

Source: Node 16 service using Framework A.
Target: Node 22 and Framework B.
Must preserve: public API, stored event schema, authentication behavior,
rate limits, and audit logs.
May change: internal modules and build system.
Rollout: canary by tenant with immediate rollback.

Inventory Before Editing

Ask Claude to map entry points, public interfaces, data stores, scheduled jobs, external integrations, feature flags, runtime configuration, and deployment scripts. Verify the map through code search and production telemetry. Identify dynamically loaded modules and operational scripts that static reading may miss.

Create a dependency table with owner, version, support status, replacement, and migration risk. Do not let the model upgrade packages merely because newer versions exist.

Capture Current Behavior

Add characterization tests around externally meaningful behavior before changing implementation. Record golden inputs and outputs for stable contracts, including error responses and edge cases. Use production traces or anonymized fixtures where policy allows.

Ask Claude to propose tests, then challenge each one: does it verify a contract or simply mirror current code? Preserve known bugs only when compatibility requires it, and document that decision explicitly.

Migrate in Reviewable Slices

Choose vertical slices that can be built, tested, and rolled back independently. A typical order is infrastructure compatibility, shared utilities, read paths, write paths, background jobs, and cleanup. Keep behavior changes separate from mechanical conversion.

For each slice, give Claude the target contract, relevant code, conventions, and test commands. Require a change summary, risk analysis, and regression tests. Review every generated dependency and configuration change.

Use Differential Testing

Run the old and new implementations against the same fixtures. Compare status codes, payloads, ordering, precision, side effects, logs, and performance. For non-deterministic fields, define normalization rules rather than ignoring the entire response.

For databases, test old application/new schema and new application/old schema combinations if rolling deployment creates those states. Verify forward and backward migration on a production-sized anonymized snapshot.

Protect Data and Operations

Make writes idempotent where possible. Use shadow reads, dual-run comparison, canaries, feature flags, and explicit rollback thresholds. Monitor error rate, latency, resource use, data reconciliation, and customer-impact metrics—not only deployment health.

Claude can help construct operational checklists, but it cannot know undocumented incident history unless you provide it. Include runbooks and known failure patterns in the review packet.

Remove the Old Path Carefully

Decommission only after the new path meets an observation window and stored data is reconciled. Remove flags, dead adapters, temporary dual writes, and obsolete dashboards in a separate cleanup change. Update ownership, diagrams, recovery procedures, and onboarding documentation.

Final Review Questions

• Are all public and persisted contracts tested?
• Can every migration slice be rolled back?
• Were generated changes reviewed for security and licensing?
• Are compatibility assumptions supported by evidence?
• Does monitoring detect silent data divergence?
• Has the team rehearsed recovery?

Claude can reduce the cost of understanding and converting legacy code. The safe migration still advances through small verified steps, with production behavior—not code similarity—as the source of truth.

A Migration Evidence Pack

Each completed slice should leave behind a compact evidence pack: linked requirements, old and new behavior tests, dependency decisions, benchmark results, security review, deployment steps, observation metrics, and rollback proof. This makes approval independent of the chat that produced the code.

Pay special attention to absence of evidence. If nobody knows whether a batch job is still used, do not delete it because static analysis finds no caller. Check schedules, telemetry, operational runbooks, and system owners. If production data contains shapes missing from fixtures, sample and anonymize them under policy before declaring compatibility.

Estimate progress by verified contracts rather than changed lines. Useful measures include interfaces covered by characterization tests, traffic exercised on the new path, data reconciliation rate, unresolved compatibility risks, and recovery time observed in rehearsal.