Legacy Code Modernization with Claude Code: Breaking Through Context Window Barriers

1# Navigate to your legacy project
2cd legacy_billing_system/
3
4# Initialize Claude Code project documentation
5claude
6# Then in the session:
7# > /init

1# Start Claude Code for systematic analysis
2claude

1# Alternatively, use Shift + Tab twice to activate plan mode
2# Then you can have a structured planning conversation:
3> Analyze this COBOL billing system and create a modernization plan. Include
4  architecture analysis, core modules, dependencies, risks, and recommended sequence.

1> /agents
2Opening subagent management interface...

1---
2name: legacy-analyzer
3description: Expert at analyzing legacy code patterns, business logic, and regulatory requirements
4tools: Read, Grep, Glob
5---
6
7You are a specialist in legacy code analysis. Focus on:
8- Identifying core business logic and critical calculations
9- Extracting validation rules and business constraints
10- Documenting regulatory compliance patterns
11- Finding self-contained modules suitable for modernization

1> Use the legacy-analyzer subagent to analyze BILLING-CALC.COB and extract business rules
2
3> Use the dependency-mapper subagent to map all dependencies in the customer management module
4
5[Both subagents work independently with separate context windows, providing focused analysis while you continue architectural planning]

1Analyzed COBOL billing system structure:
2Core modules (by priority):
31. BILLING-CALC.COB - Rate calculation engine
4   Self-contained, critical business logic
52. CUSTOMER-TIER.COB - Customer classification
6   Depends on billing calc, interfaces with credit system
73. INVOICE-GEN.COB - Invoice generation
8   Tightly coupled to legacy reporting, modernize last
9Key business rules:
10- Volume discounts: 1000, 5000, 10000 unit thresholds
11- Tax calculations round to nearest cent (regulatory)
12- Tier changes effective next billing cycle
13- Negative adjustments need manager approval
14Recommend starting with BILLING-CALC.COB - most critical and self-contained.

1---
2description: Transform legacy module to modern equivalent while preserving business logic
3---
4
5Modernize the legacy code module $ARGUMENTS:
6
71. Analyze Business Logic: Extract core calculations and validation rules
82. Modern Implementation: Create equivalent modern code with proper error handling
93. Preserve Compliance: Maintain regulatory requirements and audit trails
104. Add Testing: Generate comprehensive test suite for equivalence validation
115. Documentation: Update CLAUDE.md with patterns and decisions
12
13Ensure 100% functional equivalence with the legacy implementation.

1# Continue your previous modernization session
2claude --continue

1> /modernize-module BILLING-CALC.COB
2
3I’ll systematically modernize BILLING-CALC.COB following the established methodology:
4
51. Analyzing business logic... [extracts discount tiers, rounding rules]
62. Creating Python implementation with proper financial data types...
73. Preserving regulatory compliance patterns...
84. Generating comprehensive test suite...
95. Updating CLAUDE.md with transformation patterns...
10
11[Creates modern Python equivalent with full equivalence validation]

1# billing_engine.py - Generated by Claude Code
2from decimal import Decimal, ROUND_HALF_UP
3from dataclasses import dataclass
4from typing import Optional
5from enum import Enum
6import logging
7from datetime import datetime
8
9class CustomerTier(Enum):
10    BASIC = "BASIC"
11    PREMIUM = "PREMIUM"
12    ENTERPRISE = "ENTERPRISE"
13
14@dataclass
15class BillingCalculation:
16    """
17    Preserves exact COBOL billing logic while adding modern Python features
18    """
19    customer_tier: CustomerTier
20    usage_amount: Decimal
21    discount_rate: Decimal = Decimal('0.00')
22
23    def calculate_billing_amount(self) -> Decimal:
24        """
25        Calculate billing amount with discount application.
26        Preserves exact COBOL business logic while adding type safety.
27
28        Original COBOL logic:
29        - Premium customers get 5% discount if usage > 1000
30        - All calculations must round to nearest cent (regulatory)
31        """
32        # Apply tier-based discount logic (preserving original business rules)
33        if self.customer_tier == CustomerTier.PREMIUM:
34            if self.usage_amount >= Decimal('1000'):
35                self.discount_rate = Decimal('0.05')  # 5% discount
36            else:
37                self.discount_rate = Decimal('0.00')
38        else:
39            self.discount_rate = Decimal('0.00')
40
41        # Calculate final amount (preserving COBOL calculation method)
42        billing_amount = self.usage_amount * (Decimal('1') - self.discount_rate)
43
44        # Round to nearest cent (regulatory compliance requirement)
45        return billing_amount.quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)
46
47class ModernBillingEngine:
48    """
49    Modern Python implementation preserving COBOL business logic
50    while adding error handling, logging, and testability
51    """
52
53    def __init__(self):
54        self.logger = logging.getLogger(__name__)
55
56    def process_customer_billing(self, customer_id: str,
57                               customer_tier: str,
58                               usage_amount: str) -> dict:
59        """
60        Process billing with the same logic as original COBOL system
61        but with modern error handling and data validation
62        """
63        try:
64            # Input validation (improvement over original COBOL)
65            if not customer_id or not usage_amount:
66                raise ValueError("Customer ID and usage amount are required")
67
68            # Convert inputs to proper types
69            tier = CustomerTier(customer_tier.upper())
70            usage = Decimal(str(usage_amount))
71
72            # Apply original COBOL business logic
73            calculation = BillingCalculation(
74                customer_tier=tier,
75                usage_amount=usage
76            )
77
78            billing_amount = calculation.calculate_billing_amount()
79
80            # Enhanced logging (modern addition)
81            self.logger.info(f"Billing calculated for customer {customer_id}: "
82                           f"usage={usage}, tier={tier.value}, "
83                           f"discount={calculation.discount_rate}, amount={billing_amount}")
84
85            return {
86                "customer_id": customer_id,
87                "billing_amount": float(billing_amount),
88                "discount_applied": float(calculation.discount_rate),
89                "calculation_timestamp": datetime.utcnow().isoformat(),
90                "status": "SUCCESS"
91            }
92
93        except Exception as e:
94            # Comprehensive error handling (improvement over COBOL)
95            self.logger.error(f"Billing calculation failed for {customer_id}: {e}")
96            return {
97                "customer_id": customer_id,
98                "status": "ERROR",
99                "error_message": str(e),
100                "calculation_timestamp": datetime.utcnow().isoformat()
101            }

1---
2description: Generate comprehensive equivalence tests for modernized vs legacy code
3---
4
5Generate comprehensive validation tests for $ARGUMENTS:
6
71. Equivalence Tests: Verify identical behavior between legacy and modern implementations
82. Business Logic Tests: Test all calculations, validations, and business rules
93. Edge Cases: Cover boundary conditions, error scenarios, and regulatory edge cases
104. Performance Baseline: Compare performance characteristics where relevant
115. Compliance Verification: Ensure regulatory requirements are maintained
12
13Use parameterized tests for efficiency. Document any acceptable differences.

1> /validate-equivalence billing_engine.py vs BILLING-CALC.COB
2
3I’ll create comprehensive equivalence tests following the validation methodology:
4
51. Analyzing legacy behavior patterns...
62. Creating parameterized test cases...
73. Testing business logic equivalence...
84. Validating regulatory compliance...
95. Documenting test coverage...
10
11[Generates complete test suite with business logic validation]

1import pytest
2from decimal import Decimal
3from billing_engine import ModernBillingEngine, CustomerTier, BillingCalculation
4
5class TestBillingEngineBusinessLogic:
6    """
7    Comprehensive tests that verify the modernized system produces
8    identical results to the original COBOL system for all business scenarios
9    """
10
11    def setup_method(self):
12        self.billing_engine = ModernBillingEngine()
13
14    @pytest.mark.parametrize("tier,usage,expected_discount,expected_amount", [
15        # Test cases derived from original COBOL system documentation
16        ("BASIC", "500", Decimal('0.00'), Decimal('500.00')),
17        ("BASIC", "1500", Decimal('0.00'), Decimal('1500.00')),
18        ("PREMIUM", "999", Decimal('0.00'), Decimal('999.00')),
19        ("PREMIUM", "1000", Decimal('0.05'), Decimal('950.00')),
20        ("PREMIUM", "2000", Decimal('0.05'), Decimal('1900.00')),
21    ])
22    def test_billing_calculation_matches_cobol_output(self, tier, usage, expected_discount, expected_amount):
23        """Verify calculations match legacy system exactly"""
24        result = self.billing_engine.process_customer_billing(
25            customer_id="test_customer",
26            customer_tier=tier,
27            usage_amount=usage
28        )
29
30        assert result['status'] == 'SUCCESS'
31        assert Decimal(str(result['billing_amount'])) == expected_amount
32        assert Decimal(str(result['discount_applied'])) == expected_discount
33
34    def test_edge_cases_and_boundary_conditions(self):
35        """Test edge cases that caused issues in the original COBOL system"""
36
37        # Test exactly at discount threshold
38        result = self.billing_engine.process_customer_billing(
39            customer_id="edge_test",
40            customer_tier="PREMIUM",
41            usage_amount="1000.00"
42        )
43        assert result['billing_amount'] == 950.0
44
45        # Test just below threshold (no discount should apply)
46        result = self.billing_engine.process_customer_billing(
47            customer_id="edge_test",
48            customer_tier="PREMIUM",
49            usage_amount="999.99"
50        )
51        assert result['billing_amount'] == 999.99
52
53    def test_regulatory_compliance_rounding(self):
54        """Verify rounding behavior matches regulatory requirements"""
55        # Test case that verifies proper cent rounding
56        calculation = BillingCalculation(
57            customer_tier=CustomerTier.PREMIUM,
58            usage_amount=Decimal('1000.333')  # Should round to nearest cent
59        )
60        result = calculation.calculate_billing_amount()
61
62        # Verify result has exactly 2 decimal places and proper rounding
63        assert result == Decimal('950.32')  # (1000.333 * 0.95) = 950.31635 -> 950.32
64
65    def test_error_handling_improvements(self):
66        """Test modern error handling that wasn't in original COBOL"""
67        # Test missing customer ID
68        result = self.billing_engine.process_customer_billing(
69            customer_id="",
70            customer_tier="PREMIUM",
71            usage_amount="1000"
72        )
73        assert result['status'] == 'ERROR'
74        assert 'required' in result['error_message']
75
76        # Test invalid customer tier
77        result = self.billing_engine.process_customer_billing(
78            customer_id="test",
79            customer_tier="INVALID_TIER",
80            usage_amount="1000"
81        )
82        assert result['status'] == 'ERROR'

1# Start your modernization session
2claude

1# After extensive analysis and code generation, when context is getting full
2> /compact
3  ⎿  Compacted. ctrl+r to see full summary