Legacy Modernization Path
Who it's for
Engineers modernizing a brownfield system where agents love to rewrite and you need behavior preservation, strangler patterns, and honest blast radius.
Prerequisites
- A legacy codebase with tests you partially trust (or a plan to characterize before changing)
- Authority to land incremental PRs (no big-bang mandate without a flag)
- Production access or a staging environment that mirrors enough to matter
Ordered modules
- Why Agents Fail — rewrite bias and shallow understanding
- Legacy Refactor — primary playbook
- Refactor plan template — invariants first
- Migration — when the platform actually changes
- Architecture Erosion — don't "modernize" into a new mess
- Decision Records — record strangler choices
- Testing AI Code — characterization and regression bars
- Node Backend Refactor case study — concrete brownfield arc
- Architecture Recovery — when prior agent work already hurt
- Recovery — abort criteria when the agent goes wide
Exercises
- Write characterization tests (or scripts) for one hotspot before any agent refactor session.
- Fill a refactor plan with explicit invariants and three mergeable steps; forbid steps that aren't independently shippable.
- Run one agent session with blast-radius paths in the prompt; reject any file outside the list.
- Produce an ADR for "strangle vs rewrite" on one subsystem; link it from CLAUDE.md.
Capstone
Complete one strangler or behavior-preserving refactor slice in production: plan → agent-assisted steps → characterization/regression green → ADR + ARCHITECTURE update. Document one agent attempt you reverted and why.
Expected outcome
You can use agents on legacy code without accepting drive-by rewrites — invariants are explicit, steps are mergeable, and recovery is rehearsed.
Related
- Learning Paths
- Staff Engineer path — architecture control
- Shallow Implementation
- Production Debugging