Modernizing Legacy Code with Claude Code: Step-by-Step Guide

Core Principles

• Don't do it all at once (risk too high)
• Write tests first (safety net)
• Replace incrementally (Strangler Fig)

Step 1: Understand the Code

claude "Analyze src/legacy/:
1. What does this module do externally?
2. Internal dependency map
3. Entry points called from outside
4. Data input/output formats

Focus on minimum info for safe testing."

Step 2: Characterization Tests

claude "Write characterization tests for src/legacy/payment-processor.js.
Purpose: safety net, not ideal behavior.
Tests must pass before AND after any refactor.
Output: test/legacy/payment-processor.test.js"

Step 3: Strangler Fig Pattern

# Create new interface
claude "To replace legacy payment processor:
1. Create src/interfaces/payment-processor.ts
2. Create src/services/payment-processor-v2.ts (empty)
3. Create feature flag in config/feature-flags.ts

Skeleton only, no implementation yet."

Step 4: Migrate Feature by Feature

claude "Implement processPayment in v2:
- Fully compatible input/output with v1
- Uses async/await, TypeScript, Prisma
- All characterization tests pass
- Only active when feature flag is true"

Common Modernization Patterns

# Callbacks to async/await
claude "Convert Promise.then chains in src/api/ to async/await."

# Global state to DI
claude "Refactor global db in src/legacy/db.js to dependency injection."

# Mixed concerns to layers
claude "Split src/legacy/api.js into routes/, services/, repositories/."

Progress Tracking

claude "Generate modernization progress report:
- Legacy code remaining (lines + files)
- Migration % complete
- Test coverage change
- Priority remaining tasks

Compare src/legacy/ vs src/"

Summary

Phase	Claude Code Role
Understand	Analysis report
Safety net	Auto-generate tests
Replace	Code conversion
Verify	Comparison report

No tests = no modernization. This rule stands with or without AI.

---

This article is an excerpt from the Claude Code Complete Guide (7 chapters), available on note.com.
myouga (@myougatheaxo) - VTuber axolotl. Sharing practical AI development tips.