Expert Modernization Agent

Your comprehensive agent for guiding complete project modernization — upgrading tech stacks, migrating frameworks, modernizing architecture patterns, and transitioning codebases to current standards through a structured, phased workflow.

When to Use This Agent

Choose Expert Modernization Agent when:

• Modernizing a legacy codebase to current frameworks and patterns
• Migrating between major framework versions (Angular 8→18, .NET Framework→.NET 8)
• Upgrading build systems, package managers, or toolchains
• Transitioning from monolith to microservices or modular monolith
• Establishing modern development practices (TypeScript, testing, CI/CD)

Consider alternatives when:

• You need a small, focused upgrade — handle it directly
• You need new feature development — use a developer agent
• You need architecture design without migration — use an architect agent

Quick Start

Copy
# .claude/agents/modernization.yml
name: Expert Modernization Agent
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Full-stack modernization agent for tech stack upgrades, framework migrations, and architecture transitions

Example invocation:

claude "Assess our legacy Express.js application and create a modernization plan — we want to migrate to Fastify with TypeScript, add Vitest testing, and implement structured logging"

Core Concepts

Modernization Workflow

Phase	Activity	Deliverable
1. Assessment	Analyze current state, dependencies, patterns	Current state report
2. Strategy	Define target state, migration path, risk areas	Modernization plan
3. Foundation	Update build tools, config, type system	Infrastructure ready
4. Migration	Convert code module by module	Working migrated code
5. Verification	Test, benchmark, validate	Quality confirmation
6. Cleanup	Remove legacy code, update documentation	Clean codebase

Migration Strategy Patterns

Big Bang (avoid if possible):
  └─ Rewrite everything at once
  └─ High risk, no incremental value

Strangler Fig (preferred):
  └─ Wrap legacy with new facade
  └─ Migrate one module at a time
  └─ Legacy shrinks as new grows

Branch by Abstraction:
  └─ Create abstraction over legacy
  └─ Build new implementation behind abstraction
  └─ Switch over when ready

Parallel Run:
  └─ Run old and new simultaneously
  └─ Compare outputs for correctness
  └─ Cut over when confident

Configuration

Parameter	Description	Default
migration_strategy	Strategy (strangler-fig, branch-abstraction, parallel)	strangler-fig
risk_tolerance	Risk appetite (conservative, balanced, aggressive)	conservative
testing_requirement	Test coverage requirement	existing + new
backwards_compat	Maintain backwards compatibility during migration	true
documentation	Document changes during migration	true

Best Practices

1. Assess before you modernize. Map all dependencies, identify tightly-coupled modules, measure test coverage, and catalog technical debt before writing a migration plan. Surprises during migration are expensive — discover them during assessment.

2. Use the strangler fig pattern for incremental migration. Replace one module at a time behind a routing layer or abstraction. Each migration step delivers value independently, and you can pause or reverse at any point. Big-bang rewrites fail more often than they succeed.

3. Maintain existing test coverage throughout migration. Never delete tests during modernization — they're your safety net. Run the existing test suite after each migration step. If tests fail, fix the migration before proceeding.

4. Upgrade dependencies in a separate step from code migration. Don't change the framework version and rewrite code in the same PR. Upgrade dependencies first, fix breaking changes, verify everything works, then start code modernization. This isolates variables.

5. Keep the legacy system running until the new system is proven. Don't decommission legacy code until the migrated version has run in production successfully for at least 2 weeks. Maintain the ability to roll back throughout the migration.

Common Issues

Migration stalls at 70% complete because the remaining 30% is the hardest. Teams migrate the easy modules first, leaving the most complex, tightly-coupled code for last. Tackle the riskiest module second (after the easiest one for confidence), not last.

Breaking changes cascade across the codebase during migration. When migrating a shared module, all consumers must update simultaneously. Use the adapter pattern — create a compatibility layer that both old and new code can use during the transition period.

Performance regressions after modernization go unnoticed. New frameworks, new serialization, and new abstractions may have different performance characteristics. Benchmark critical paths before and after migration. A "modern" codebase that's 3x slower is not an improvement.