Claude Code for Legacy Code Migration: Modernise 10x Faster

The Legacy Migration Problem Every CTO Knows

You have a COBOL mainframe running since 1987. Or a Java EE monolith that nobody fully understands anymore. Or a PHP application where business logic is buried in stored procedures six levels deep. The developers who built it have retired. The documentation, if it exists at all, describes a system that no longer resembles what's actually running in production.

Traditional migration approaches require an army of analysts to spend months reading the code before writing a single line of the replacement. That analysis phase alone costs millions and kills momentum. Most projects die before they reach production. According to Gartner, over 70% of legacy migration projects fail to meet their original scope, budget, or timeline targets.

Claude Code attacks the analysis bottleneck directly. It reads the codebase — all of it — understands what it does, maps the dependencies, generates documentation, and produces modernised equivalents. Our code modernisation service has used Claude Code to migrate codebases that would have taken traditional teams 36 months in under 6. The 10x figure isn't marketing. It's the analysis phase compressed from months to days.

What Claude Code Can Actually Analyse

Claude Code is a terminal-based AI coding assistant that operates on your actual codebase — not a sanitised demo or a toy project. It can be pointed at a repository of any size and asked to understand it at a structural, semantic, and business-logic level. For legacy migration, this capability is transformative.

COBOL and Mainframe Systems

Claude Code reads COBOL fluently. It understands PERFORM statements, file control entries, working storage sections, and the deeply nested conditional logic that characterises mainframe batch jobs. Point it at a COBOL program and ask it to explain what the program does in plain English, and it will produce a detailed specification. Ask it to translate that logic to Python or Java, and it produces working code with inline comments explaining every business rule.

For financial services clients migrating core banking systems, this has been the single biggest time-saver. The analysis that required a team of three COBOL specialists working for six months now takes Claude Code two days. The specialists then review and validate — their expertise goes further, and the project moves faster.

Java EE and Monolithic Applications

Java EE monoliths present a different challenge: there's usually too much code to comprehend, not too little documentation. Hundreds of thousands of lines of business logic, tightly coupled services, shared database schemas, and a transaction model that nobody wants to break. Claude Code excels at mapping this kind of system — identifying service boundaries, understanding domain models, and proposing a microservices decomposition that preserves the existing business behaviour.

The CLAUDE.md configuration file is essential here. You configure Claude Code with context about your target architecture — which cloud provider, which container platform, which frameworks — and it adapts every generated artefact accordingly. Read our CLAUDE.md configuration guide to understand how to set this up properly before starting a migration project.

PHP, Python 2, and End-of-Life Languages

PHP 5 applications, Python 2 scripts, Classic ASP pages — Claude Code handles all of them. The challenge with these systems is rarely the language itself; it's the implicit assumptions baked into the code. PHP applications that rely on deprecated function behaviour. Python 2 scripts where string handling breaks in subtle ways when moved to Python 3. Claude Code identifies these breakpoints and flags them explicitly, rather than producing code that appears to work but fails on edge cases.

A Production-Grade Migration Workflow with Claude Code

Throwing Claude Code at a legacy codebase without structure produces noise. The organisations that get 10x results follow a disciplined workflow that uses Claude Code's strengths at each stage of the migration.

Phase 1: Discovery and Documentation

Before touching a line of code, use Claude Code to build a complete understanding of what the system does. Configure your CLAUDE.md with context about the system's domain, key data entities, and known constraints. Then run a systematic discovery using Claude Code's ability to read and reason across the full codebase.

Typical discovery outputs include: a functional specification of every major module, a dependency graph showing which components call which, an inventory of external integrations and API contracts, and a list of business rules embedded in the code that no existing documentation captures. This documentation becomes the migration contract — the new system must reproduce these behaviours exactly.

# Example CLAUDE.md configuration for legacy migration
# Instructs Claude Code to behave consistently across the project

MIGRATION_TARGET: Python 3.12 / FastAPI / PostgreSQL
CLOUD_TARGET: AWS ECS Fargate
PRESERVE_BEHAVIOUR: true — flag any logic deviations
TEST_FRAMEWORK: pytest with behaviour-driven naming
DOMAIN_CONTEXT: Insurance premium calculation engine
  - Primary entities: Policy, Endorsement, PremiumRate, RiskFactor
  - Key constraint: Actuarial calculations must match legacy output to 4 d.p.
  - External integrations: ISO rating bureau, State filing systems

Phase 2: Incremental Translation

Never attempt a big-bang migration with Claude Code. Instead, carve out modules at the boundaries identified in Phase 1 and translate them one at a time. Claude Code can translate a single COBOL program or Java service, generate unit tests that exercise its logic, and produce a side-by-side comparison of the original and translated output for any given input.

The sub-agent capability in Claude Code makes this particularly powerful. You can orchestrate multiple Claude Code instances working on different modules in parallel, each operating in its own context with shared configuration from CLAUDE.md. A migration that once required serialised work across a small team can now be parallelised significantly.

Phase 3: Test Generation and Validation

The most dangerous part of any migration is the unknown unknowns — the business rules that only surface when real production data hits the system. Claude Code addresses this by generating comprehensive test suites from the original source code, including tests for edge cases it identifies in the logic itself.

For a COBOL batch job, this means generating Python tests that feed the same input records through both the original (running in emulation) and the new code, then comparing outputs. Any discrepancy is flagged for human review. This approach has caught business logic errors that would have been invisible in functional testing but catastrophic in production — particularly in financial calculations and regulatory reporting.

COBOL to Python: A Real-World Example

To make this concrete, consider a common scenario: a financial services firm with a COBOL program that calculates interest accruals for a portfolio of bonds. The program is 4,200 lines, written in 1994, and the original developer left the firm twelve years ago. There is no functional specification. The only documentation is the code itself.

In the legacy approach, a COBOL specialist spends two weeks reading the code and producing a specification. A Python developer spends another two weeks building the replacement. Testing takes a further two weeks. Six weeks total, and that's for a single program in a system that may contain hundreds.

With Claude Code: the analysis of the COBOL program takes approximately 90 minutes. Claude Code produces a plain-English specification, identifies the key business rules (day count conventions, accrual basis, compounding logic), and generates a Python equivalent with full unit tests. A developer reviews the output in a further 2-3 hours, focusing on the flagged edge cases and validating the test results. Total time: one day.

Scaled across 200 programs, that's the difference between a 24-month migration and a 3-month migration. Our code modernisation service uses this workflow as the foundation of every migration engagement. The economics are simply impossible to ignore.

What Claude Code Cannot Do (And What You Still Need Humans For)

Claude Code is an extraordinary migration accelerator, but it is not a replacement for engineering judgement. There are categories of work where human expertise is not just helpful but essential, and confusing these boundaries causes project failures.

Architectural decisions require human ownership. Claude Code can propose a microservices decomposition, but it cannot weigh the organisational factors that determine whether that decomposition is viable — team structure, operational maturity, infrastructure budget, tolerance for distributed systems complexity. These decisions belong to your architects.

Business rule validation requires domain experts. When Claude Code translates a calculation and produces a result that differs from the legacy system's output by 0.001%, that might be acceptable rounding or it might represent a regulatory compliance failure. Only your actuaries, compliance officers, or domain specialists can make that determination.

Data migration requires specialist skills. Claude Code helps with schema translation and ETL script generation, but migrating decades of production data across systems — managing referential integrity, handling historical state, managing cutover — requires a data migration specialist with experience doing exactly this under production conditions. Our enterprise implementation service provides this specialist capability alongside Claude Code tooling.

Production cutover requires operational expertise. The migration itself — traffic routing, parallel running, rollback procedures, incident response — is a live operations challenge that no AI tool automates. You need engineers with production experience who have done this before.

Setting Up Claude Code for Enterprise-Scale Migrations

Running Claude Code on a personal laptop is very different from running it as part of an enterprise migration programme with dozens of engineers. There are configuration, governance, and security considerations that must be addressed before you start.

For enterprise Claude Code deployments, the key considerations are: IP ownership of the generated code (use Anthropic's enterprise agreement which assigns IP to your organisation), which model tier to use (Claude Sonnet for standard translation tasks, Claude Opus for complex architectural reasoning), usage monitoring to manage token costs on large codebases, and access controls to ensure legacy code does not leak through personal API accounts.

The Claude Code hooks system is particularly valuable in migration contexts. You can configure hooks that automatically run your test suite after every code generation step, reject outputs that fail linting or style checks, and log all Claude Code interactions for audit purposes. This brings the AI's outputs into your existing engineering quality processes rather than creating a separate AI-generated code lane that bypasses governance.

If your organisation operates in financial services, healthcare, or another regulated sector, Claude AI governance setup must happen before migration work begins. The generated code may contain business logic that's subject to audit — you need a complete record of how it was produced.

The Business Case: What the ROI Actually Looks Like

Modernisation projects are notoriously hard to cost-justify because the benefits are diffuse and deferred — lower maintenance costs, faster feature velocity, reduced risk. Claude Code changes the ROI model by compressing the timeline so dramatically that the payback period shrinks from years to months.

Consider a typical mid-size enterprise with a Java EE monolith supporting a critical business process. Traditional migration: 18 months, £2.8M in contractor and internal resource costs, a high-risk cutover, and a 60% chance of a scope reduction. With Claude Code-assisted migration: 5 months, £900K in total programme costs, incremental module-by-module cutover, and a full-scope delivery. The 3.5x cost reduction alone justifies the investment; the faster delivery and lower risk are additional benefits.

If you're building the business case internally, book a free strategy call with our architects. We'll help you scope the migration, estimate the timeline, and build a number that your CFO can interrogate.