Claude Code modernizes a legacy COBOL codebase

Fahim Muntashir on Unsplash" data-stock-image="true" width="100%" style="object-fit: cover;" data-attribution-id="ba60a1e" data-query=developer coding on laptop data-src-1="https://images.unsplash.com/photo-1630442923896-244dd3717b35?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w1NzQyNTd8MHwxfHNlYXJjaHwxfHxkZXZlbG9wZXIlMjBjb2RpbmclMjBvbiUyMGxhcHRvcHxlbnwwfDB8fHwxNzYzMTQ2NjAyfDA&ixlib=rb-4.1.0&q=80&w=1080" data-alt-1="black and white hp laptop computer" data-query-1="developer coding on laptop" data-id-1="pAgCpLoYXdQ" data-username-1="Fahim Muntashir" data-userlink-1="https://unsplash.com/@f12r" data-src-2="https://images.unsplash.com/photo-1710770563074-6d9cc0d3e338?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w1NzQyNTd8MHwxfHNlYXJjaHwyfHxkZXZlbG9wZXIlMjBjb2RpbmclMjBvbiUyMGxhcHRvcHxlbnwwfDB8fHwxNzYzMTQ2NjAyfDA&ixlib=rb-4.1.0&q=80&w=1080" data-alt-2="a man sitting in front of a laptop computer" data-query-2="developer coding on laptop" data-id-2="vWJtYRfE_rw" data-username-2="Ibrahim Yusuf" data-userlink-2="https://unsplash.com/@its_ibrahim" data-src-3="https://images.unsplash.com/photo-1638029202288-451a89e0d55f?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w1NzQyNTd8MHwxfHNlYXJjaHwzfHxkZXZlbG9wZXIlMjBjb2RpbmclMjBvbiUyMGxhcHRvcHxlbnwwfDB8fHwxNzYzMTQ2NjAyfDA&ixlib=rb-4.1.0&q=80&w=1080" data-alt-3="a man using a laptop computer on a wooden table" data-query-3="developer coding on laptop" data-id-3="14JOIxmsOqA" data-username-3="Fahim Muntashir" data-userlink-3="https://unsplash.com/@f12r" data-src-4="https://images.unsplash.com/photo-1677506048892-edde55cf3277?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w1NzQyNTd8MHwxfHNlYXJjaHwyfHx0ZWFtJTIwYnJhaW5zdG9ybWluZyUyMHdoaXRlYm9hcmQlMjBmbG93Y2hhcnR8ZW58MHwwfHx8MTc2MzE0NjYwMnww&ixlib=rb-4.1.0&q=80&w=1080" data-alt-4="a man standing in front of a white board" data-query-4="team brainstorming whiteboard flowchart" data-id-4="4wSnhAT8d9g" data-username-4="Paymo" data-userlink-4="https://unsplash.com/@paymo" data-src-5="https://images.unsplash.com/photo-1758873272648-baed343cdc8f?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w1NzQyNTd8MHwxfHNlYXJjaHwxfHx0ZWFtJTIwYnJhaW5zdG9ybWluZyUyMHdoaXRlYm9hcmQlMjBmbG93Y2hhcnR8ZW58MHwwfHx8MTc2MzE0NjYwMnww&ixlib=rb-4.1.0&q=80&w=1080" data-alt-5="Two people collaborating on a chalkboard with diagrams." data-query-5="team brainstorming whiteboard flowchart" data-id-5="NFAmq-6gR7c" data-username-5="Vitaly Gariev" data-userlink-5="https://unsplash.com/@silverkblack" />

Photo by Fahim Muntashir on Unsplash

Discovery and documentation 📚

Alex begins with a familiar problem: a medium-sized credit card management system with almost no documentation. That system contains roughly 100 files including COBOL programs, copybooks, and JCL scripts. Critical business logic and regulatory rules are buried in code written by people who have long since left, and COBOL expertise is scarce. The task is to turn that opaque mess into something maintainable and migratable.

Instead of manual spelunking, Alex uses Claude Code to automate discovery. The first step is creating a focused subagent called the "COBOL documentation expert." Subagents run in parallel with isolated contexts so the main process stays clean. With Thinking Mode enabled, Claude Code builds a to-do list covering all 94 files and tracks progress so nothing is processed twice.

The output is far more than line-by-line comments. For each program Claude extracts end-to-end business workflows. Take the interest calculation program CBACT04C as an example. Claude mapped how it:

• Reads transaction category balances
• Looks up interest rates by account group
• Applies fallback rules for missing rates
• Updates account records

Claude doesn't stop at human-readable explanations. It also generates plain-text indices like Catalog.txt to translate cryptic names (for example, mapping CBACT04C to "Interest Calculator Batch Program") and Relationships.txt which lists dependencies in a simple pipe-delimited format. From those indices Claude produced mermaid diagrams showing the daily batch processing workflow, clarifying how data flows from transaction input through posting, interest calculation, and statement generation.

In the demo run Alex left Claude Code running for an hour and it drafted over 100 pages of documentation. The system can run for much longer—over 30 hours autonomously—so the same techniques scale to larger, real-world codebases.

Migration planning 🛠️

Once the codebase is documented, planning the migration is the next priority. Alex switches Claude Code into planning mode so it thinks through the migration strategy without changing files prematurely.

For the interest calculation feature (formerly CBACT04C), Claude analyzed COBOL-specific patterns like line break processing and multi-file coordination, then proposed a five-phase migration plan:

1. Create the project structure
2. Translate data models from copybooks to Java classes
3. Build an IO layer compatible with the original file formats
4. Convert business logic while preserving COBOL-specific behaviors
5. Create a dual test harness for side-by-side verification

This structured approach is important. A migration that simply translates syntax will break subtle business rules or file handling quirks. Claude's plan explicitly preserves behaviors that are unique to the COBOL runtime and batch environment.

Migration execution 🔁

With the plan in place, Claude Code executes the migration for the selected feature into idiomatic Java. The goal is not one-to-one text translation but to produce code a modern team will maintain.

Key technical outputs included:

• Java project skeleton with proper packaging and build scripts.
• Data model translation where copybook structures become Java classes with appropriate types and validation logic.
• IO layer that reads and writes the original mainframe-style files so the migrated code can interchange data with the legacy system during a transition.
• Business logic conversion that preserves corner cases, fallback rules, and calculation order.
• Modern safety features such as error handling, logging, and design patterns that make the code maintainable.

Claude also recommended platform choices for testing: GNU COBOL 3.2.0 for running the original codebase, and Java 17 for the new implementation. The result is not just working Java but idiomatic Java—clean classes, clear interfaces, and patterns that fit into a modern development workflow.

Verification and testing ✅

Migration without rigorous verification is risky. Alex asked Claude Code to build a dual test harness to validate the new Java code against the original COBOL program.

Claude generated multiple test data files and ran them through both implementations. The comparison went beyond final outputs. It verified:

• Intermediate calculation values
• File reads and writes, including exact data layouts
• All business rule branches and edge cases

"The result was perfect bit-for-bit fidelity,"

This is the benchmark you want when replacing critical systems: every calculation, every fallback rule, and every edge case preserved exactly. Achieving bit-for-bit fidelity required careful handling of file formats and order of operations, plus tests that exercise hairy corner cases.

Scaling and practical takeaways 🚀

While the demo application is smaller than most enterprise mainframe estates, the techniques scale. Here are practical lessons and recommendations based on Alex's process:

• Automate discovery first. Generate readable documentation, catalogs, and dependency graphs before touching code.
• Use isolated subagents for focused tasks like documentation extraction, data model translation, or test generation to keep context clean.
• Plan migrations in phases and don’t rush into code edits. Planning mode helps think through IO, data models, and behavior preservation.
• Preserve file interfaces during rollout by building IO compatibility layers so new code can interoperate with legacy files during a transition period.
• Verify thoroughly — compare intermediate values, not just final outputs. Aim for bit-for-bit fidelity where regulations or accounting require it.
• Make the result maintainable by producing idiomatic target-language code with logging, error handling, and clear class boundaries.

Checklist for a migration project

1. Run automated discovery to produce a file catalog and dependency map.
2. Create visual workflow diagrams to align engineering and business stakeholders.
3. Design a phased migration plan that includes a dual-run verification strategy.
4. Translate data models and build compatible IO layers before converting business logic.
5. Build test harnesses that compare intermediate and final outputs.
6. Iterate until parity is proven, then cut over incrementally.

Final thoughts 🌟

Modernizing legacy COBOL systems is less about chopping code and more about managing risk. The combination of automated discovery, careful planning, and rigorous verification lets teams move critical functionality into maintainable languages without losing business behavior. Alex’s run shows that with the right tools you can generate deep documentation, create a robust migration plan, and achieve production-grade Java that passes exhaustive, bit-for-bit verification.

For any team wrestling with a legacy codebase, the priority should be clarity first, migration second, and verification continuous. That order keeps projects predictable and minimizes surprise behavior when systems touch real customers and regulated processes.