CHAPTERS
Demo setup: Using Claude Code on an AWS COBOL mainframe sample repo
The video introduces a practical demo of modernizing a legacy COBOL codebase using Claude Code. It frames the target system as AWS’s Mainframe Modernization demo repository: a medium-sized credit card management system with ~100 artifacts (COBOL, copybooks, JCL).
- •Goal: modernize a legacy COBOL system with Claude Code
- •Demo target: AWS Mainframe Modernization demo repository
- •System scope: credit card management, ~100 files
- •Artifact types include COBOL programs, copybooks, and JCL scripts
Why discovery is hard in legacy COBOL: missing docs and lost tribal knowledge
The first phase focuses on discovery/documentation, emphasizing that many COBOL codebases have little to no documentation. Critical business logic and compliance rules often live only in code, while original authors are gone and COBOL expertise is scarce.
- •Legacy systems often lack usable documentation
- •Business logic and regulatory requirements are embedded in code
- •Original developers have left; knowledge is lost
- •COBOL-skilled hiring is difficult
Creating a COBOL documentation subagent and running parallel analysis safely
Claude Code is configured with a specialized subagent dedicated to COBOL documentation and translation. The subagent model supports parallel work with isolated context windows to prevent cluttering or confusing the main thread.
- •Use Claude Code /agent to create a specialized subagent
- •Subagent role: COBOL documentation expert and translator
- •Parallel invocation enables faster coverage
- •Isolated context windows reduce main-thread context pollution
Full-repo architecture pass: file-by-file to-do tracking to avoid gaps
With thinking mode enabled, Claude Code analyzes the codebase architecture and creates a structured to-do list covering all 94 files. Progress tracking ensures each file is processed once and nothing is skipped.
- •Thinking mode used for deeper architecture analysis
- •To-do list enumerates all 94 files
- •Progress tracking prevents duplicate processing
- •Ensures complete coverage across the repo
Deep program documentation example: Interest calculation workflow (CBACT04C)
The demo highlights how Claude’s documentation goes beyond inline comments by reconstructing end-to-end business workflows. Using CBACT04C as an example, Claude extracts how balances are read, rates are looked up, fallback rules applied, and records updated.
- •Documentation focuses on business workflow, not just code structure
- •CBACT04C: reads transaction category balances
- •Looks up interest rates by account group
- •Applies fallback-rate business rules
- •Updates account records accordingly
Building navigational indices: name translation catalog + dependency relationships map
Claude generates two plain-text memory files to make the legacy system understandable at a glance. One translates cryptic program names into human-readable labels; the other records dependencies in a simple, machine-friendly pipe-delimited format.
- •Creates Catalog.text to translate cryptic program names
- •Example: CBACT04C → interest calculator batch program
- •Creates Relationships.text to map dependencies
- •Pipe-delimited format supports easy parsing and tooling
System visualization: Mermaid diagrams of the daily batch dataflow pipeline
Using the indices, Claude produces Mermaid diagrams that map the daily batch processing workflow. The visualization shows how data moves from transaction input through posting and interest calculation to customer statements.
- •Generates Mermaid diagrams from the dependency indices
- •Produces an end-to-end daily batch workflow map
- •Traces dataflow from transaction input to downstream steps
- •Pipeline includes posting, interest calculation, and statement generation
Autonomous documentation at scale: hour-long run producing 100+ pages
The demo run continues autonomously for an hour and produces over a hundred pages of documentation. The narrator notes that Claude Code can operate for much longer (over 30 hours) and the approach scales to larger enterprise codebases.
- •Claude Code ran continuously for ~1 hour in the demo
- •Output: 100+ pages of documentation
- •Capability: can run autonomously for 30+ hours
- •Techniques are positioned as scalable to much larger codebases
Phase two begins: switching to planning mode for migration strategy
After documentation, the demo moves into migration and verification by targeting a core feature for conversion to Java. Planning mode is used to reason through the migration approach before making edits, reducing rework and mistakes.
- •Phase two: migration and verification
- •Target: migrate a core COBOL feature to Java
- •Switch to planning mode to avoid premature edits
- •Emphasis on end-to-end strategy before implementation
Assessing COBOL-specific complexity before translation
Claude analyzes the interest program (formerly CBACT04C) and identifies tricky legacy patterns that need faithful handling in a new language. Examples include line-break processing and multi-file coordination that can easily cause behavioral drift if missed.
- •Analyzes CBACT04C as the migration candidate
- •Identifies complex COBOL patterns to preserve
- •Examples: line break processing nuances
- •Examples: multi-file coordination behavior
Five-phase migration plan: structure, models, IO compatibility, logic fidelity, dual harness
Claude proposes a five-phase plan to migrate safely and systematically. It covers setting up a Java project, translating copybooks into Java models, implementing IO compatible with mainframe file formats, porting business logic while preserving COBOL behaviors, and creating a dual test harness for COBOL vs. Java comparison.
- •Phase 1: create Java project structure
- •Phase 2: translate copybook data models into Java classes
- •Phase 3: build an IO layer compatible with original file formats
- •Phase 4: convert business logic while preserving COBOL-specific behaviors
- •Phase 5: create dual test harness (GNU COBOL 3.2.0 and Java 17)
Producing maintainable Java: idiomatic design, logging, and error handling
The resulting Java output is presented as more than a mechanical syntax conversion. Claude generates proper classes and applies modern practices (design patterns, logging, and error handling) so a contemporary team can maintain the code.
- •Output exceeds direct syntax translation
- •Creates well-structured Java classes
- •Applies appropriate design patterns
- •Adds error handling and logging
- •Focus on maintainability for modern teams
Verification for behavioral equivalence: multi-level comparisons and bit-for-bit fidelity
Verification checks that Java behavior matches COBOL across outputs and internal steps. Claude generates test data and compares not only final results but intermediate calculations, file writes, and transformations—achieving exact, bit-for-bit fidelity.
- •Creates multiple test data files for validation
- •Runs tests against both COBOL and Java implementations
- •Compares intermediate calculations, not just final outputs
- •Checks file writes and data transformations
- •Result: perfect bit-for-bit fidelity across rules and edge cases
Closing takeaway: scalable modernization with new developer productivity
The video concludes by emphasizing that while the demo is smaller than many real COBOL estates, the workflow scales. Claude Code is positioned as enabling faster, more confident modernization than was feasible a year earlier.
- •Demo is smaller than typical enterprise COBOL estates
- •Approach is intended to scale to larger systems
- •Promise: increased confidence and efficiency in modernization
- •Claim: capabilities were not feasible 12 months earlier
