AI Agents for Legacy Code Modernization: The Developer’s Week-by-Week DIY Guide

Architectural Inventory

Before changing anything, you need to know what you have. Launch a Claude Code session and ask it to produce an architectural inventory of the codebase. This is the single most valuable task for an AI agent in legacy work — what takes a developer weeks of code reading takes an agent hours.

The inventory should include:

• Module map — every major directory, its purpose, and its entry points
• Dependency graph — which modules depend on which, including circular dependencies
• Technology inventory — language versions, frameworks, libraries, and their ages
• Test coverage — which modules have tests and which have zero coverage
• Dead code candidates — functions, routes, and files that appear unreachable

## Example prompt for Claude Code

Read this entire codebase and produce an architectural inventory. For each
top-level directory/module:
1. Its purpose (one sentence)
2. Key files and entry points
3. Dependencies (other modules it imports from)
4. External dependencies (third-party packages)
5. Test coverage (has tests / no tests / partial)
6. Language version and framework version

Then identify: circular dependencies, dead code candidates (unreachable
functions/routes), and the 5 riskiest modules (most complex, least tested,
most dependencies).

Dependency Analysis and Dead Code Removal

Use ast-grep and Claude Code together to map internal dependencies at the function/class level. Then use an agent to remove confirmed dead code — this is the safest first change because deleting unused code cannot break anything that was actually running.

Run 2–3 parallel agents via amux, each targeting a different module’s dead code:

## Agent 1: Remove dead code in /src/legacy-auth/
## Agent 2: Remove dead code in /src/legacy-billing/
## Agent 3: Remove dead code in /src/legacy-reports/

Each agent: analyze imports, find unreachable functions, remove them,
run existing tests to confirm nothing breaks. Commit each removal
separately with a clear message.

Modernization Plan

With the architectural inventory and clean dependency graph in hand, produce the modernization plan. This is the one step that must be human-driven — the agent provides data, you make the decisions:

• Module priority order — which modules to modernize first (start with the least-coupled, best-tested modules)
• Migration targets — what each module should look like after modernization (new framework, new API style, new patterns)
• Risk assessment — which modules need careful human review vs. which can be agent-driven
• Parallelism plan — which modules can be refactored simultaneously (no shared dependencies)

Characterization Tests

Characterization tests capture what the code actually does, not what it should do. Even if the code has bugs, the tests document the current behavior. This is critical: during refactoring, you need to know whether a behavior change was intentional or accidental.

Run 4–6 agents in parallel, each generating characterization tests for a different module:

## Prompt template for each agent

Read /src/MODULE_NAME/ and generate characterization tests using
FRAMEWORK (pytest/Jest/PHPUnit).

For every public function and API endpoint:
1. Write a test that captures the current input/output behavior
2. Include edge cases you can identify from the code
3. Test error paths and exception handling
4. Do NOT fix bugs — document the current behavior, even if it looks wrong
5. Add a comment "# Characterization test — captures legacy behavior"
   to distinguish from intentional tests

Run the tests and ensure they all pass against the current code.

Use pytest for Python, Jest for JavaScript/TypeScript, PHPUnit for PHP, JUnit for Java. Match the testing framework to the ecosystem.

Integration Tests and Human Review

Characterization tests cover individual modules. Integration tests cover the interactions between modules — this is where legacy systems hide their worst bugs. Generate integration tests for the critical paths identified in Week 1’s architectural inventory.

Then spend Day 5 reviewing the generated tests. Look for:

• False confidence — tests that always pass because they test the wrong thing
• Missing edge cases — boundary conditions that the agent could not infer from code alone
• Business logic gaps — tests that capture the how but miss the why (add intent comments yourself)

Parallel Refactoring Sprint

Launch 4–8 agents, each in its own git worktree, each refactoring a different module according to the modernization plan from Week 1:

## Example: 6 agents refactoring 6 modules

Agent 1 (worktree: wt-auth)    → Refactor /src/auth/ from PHP 5 → PHP 8
Agent 2 (worktree: wt-billing) → Refactor /src/billing/ from jQuery → React
Agent 3 (worktree: wt-reports) → Refactor /src/reports/ from callbacks → async/await
Agent 4 (worktree: wt-api)     → Refactor /src/api/ from REST v1 → REST v3
Agent 5 (worktree: wt-models)  → Refactor /src/models/ from raw SQL → ORM
Agent 6 (worktree: wt-config)  → Refactor /src/config/ from env files → typed config

Each agent:
1. Create a feature branch in its worktree
2. Refactor the module according to the spec
3. Run the module's characterization tests — they MUST still pass
4. Run the integration tests that touch this module
5. Commit with a clear message describing the migration

Monitor all sessions from the amux dashboard or the mobile PWA. When an agent finishes, review its diff and either approve or redirect.

Conflict Resolution and Second Pass

Some modules will have shared interfaces. When Agent 2 changes a function signature that Agent 4 also calls, you get a conflict. This is expected and manageable:

1. Merge the module with the most downstream dependencies first (usually the models/data layer)
2. Rebase other agent branches onto the updated main
3. Send each rebased agent a message to fix the conflicts: “The function signature for get_user() changed. Update your module to match the new interface and re-run tests.”
4. Run the full integration test suite after each merge

Full Integration Testing

With all refactored modules merged, run the complete test suite. Fix failures using focused agent sessions — each failure goes to an agent with the specific test, the error message, and the relevant module code.

Run Semgrep and Snyk security scans against the refactored codebase. AI agents can introduce subtle security regressions during refactoring — static analysis catches what tests miss.

Documentation and Migration Guide

Generate documentation for the modernized codebase. This is where AI agents shine — they are tireless documenters. Run 2–3 agents:

• Agent 1: Generate API documentation for all public interfaces
• Agent 2: Write a migration guide documenting every breaking change
• Agent 3: Update README, CHANGELOG, and deployment instructions

Ship

Deploy the modernized codebase. For most teams, this means a blue-green deployment or feature-flagged rollout — the legacy system stays running until the modernized version is validated in production.

• All characterization tests pass
• All integration tests pass
• Security scans clean (or known issues documented)
• Migration guide reviewed and approved
• Rollback plan documented and tested
• Monitoring/alerting configured for the new code paths