Section 7 · Lesson 3
Legacy Modernization — Recover Intent, Then Replace
The modernization trap is rewriting the how without recovering the why. Spec-driven development treats recovered intent as the system of record, then strangles the old system incrementally.
"Compiling is the beginning. Done is conformance.
The system nobody wants to touch
Every company has one: a huge, critical piece of software that everyone is terrified to change — and everyone knows must be replaced. Months or years and millions of dollars later, the rewrite is often just as buggy and confusing as the original, only written in a shinier language.
The modernization trap
Teams walk into it with the best intentions. They pour energy into the how — the code — without ever getting a real grip on the what, and most importantly the why, of the original system. That is the trap: replacing syntax while losing purpose.
Intent decay
The original purpose of the software evaporates slowly. Developers leave, documentation goes stale, and eventually nobody knows why that weird line of code exists. When the why is gone, all you have is the code — and you are stuck maintaining by patching.
Duct tape instead of design
A quick fix here, a workaround there. Nobody dares a fundamental improvement because some secret, critical business rule is buried in the tangle. Technical debt keeps piling up because the system cannot be understood, only nursed.
The AI rewrite illusion
An AI can read old code and spit out new code. Without recovered intent it creates a convincing illusion: it looks right, it passes a few demos, and it falls apart the moment real-world complexity hits production. The trap is the same — code without why.
Flip the source of truth
The old way treats code as the system of record — so you inherit every bug, workaround, and accidental complexity, and you are forced into a high-risk big-bang rewrite. Spec-driven development flips that. The written-down intent becomes the system of record. You start from a clean slate and replace the old system piece by piece.
Phase one is archaeology, not code
The first phase of an SDD modernization writes no new product code. You become a detective: recover what the system is actually supposed to be doing. Map today’s behaviour — the good, the bad, and the ugly. Lock it with characterization tests. Then translate what you discovered into a structured spec.md.
A spec the old system never had
Invariants in a clear when/then form. Scenarios: happy path, weird edge cases, error handling. And a do-not list — explicit defence against scope creep: do not change this business rule, do not add that new feature. Structure like that is gold for humans and for AI agents.
Strangle, don’t blow up
The Strangler Fig Pattern builds new services around the old system. Traffic and features move over incrementally until the legacy core is surrounded — then you turn it off. Safe, incremental, and far less risk than a big-bang cutover.
Agents as assistants, not magicians
Once the spec exists, agents become super-powered helpers: draft the first spec from old code, generate an architectural plan and data contracts, break the plan into pull-request-sized tasks, and implement those tasks with the spec and contracts as guardrails.
Done means conformance
In the old world the sigh of relief came when the new system compiled. In SDD, compiling is the beginning. The project is done when you have proven — contract tests, golden tests, production-traffic replay — that behaviour matches the spec. The goal is not completion. It is conformance.
A dataset, not a mountain of debt
That terrifying legacy system is also a rich dataset of proven, battle-tested business logic. Recover its intent, write it down, and you can build its future without inheriting its accidents.
The trap
Focus all energy on the how — the code — without recovering the what and why of the original system.
What it produces
A shiny rewrite that still carries every bug, workaround, and secret rule you never understood.
How intent decays
- 1
Origin
The weird line of code exists for a reason — a business rule, a lawsuit, a customer exception.
- 2
People leave
Original developers move on. The oral history of why the system works this way leaves with them.
- 3
Docs go stale
Wikis and comments stop matching production. The only remaining “spec” is the running code.
- 4
Patch culture
Nobody dares a real change. Fixes are duct tape. Debt piles up because intent cannot be verified.
Code as truth
Code as source of truth — you inherit bugs, workarounds, and accidental complexity, then attempt a high-risk big-bang rewrite.
Spec as record
Spec as system of record — recovered intent on a clean slate, replaced incrementally with characterization tests as a straitjacket.
Archaeology before code
Phase one writes no new product code. Recover lost intent, then lock it.
- 1
Map what it does today
The good, the bad, and the ugly — observed behaviour, not hoped-for design.
- 2
Write characterization tests
A digital straitjacket that locks current behaviour so you do not break something important by accident.
- 3
Translate into spec.md
Structured intent: invariants, scenarios, and a do-not list — the why, written down.
What goes in spec.md
When this happens, the system shall do that — no fuzzy adjectives, no tribal knowledge.
Happy path, weird edge cases, and how errors are handled — the behaviour you actually found.
Defence against scope creep: do not change this business rule; do not add that new feature during the cutover.
Strangler Fig Pattern
Surround the old system. Do not blow it up.
Step 1
Surround
Build new services around the legacy core instead of detonating it.
Step 2
Reroute
Move traffic and features to the new pieces, one slice at a time.
Step 3
Strangle
The old system is fully surrounded — no remaining critical path through it.
Step 4
Turn off
Decommission the legacy core once equivalence is proven against the spec.
- 1. Surround — Build new services around the legacy core instead of detonating it.
- 2. Reroute — Move traffic and features to the new pieces, one slice at a time.
- 3. Strangle — The old system is fully surrounded — no remaining critical path through it.
- 4. Turn off — Decommission the legacy core once equivalence is proven against the spec.
AI-assisted rebuild pipeline
Agents draft, plan, task, and implement — only after the spec exists. Guardrails, not a one-shot rewrite.
- 1
Draft spec
Read old code to propose the first spec.md — humans recover and freeze intent.
- 2
Plan & contracts
Turn the finished spec into an architectural plan and data contracts.
- 3
Task the work
Break the plan into pull-request-sized, independently verifiable tasks.
- 4
Implement with guardrails
Build each task against the spec and contracts — not against a demo script.
What this looks like in practice
About 18 months estimated → 6 weeks
A large migration internally estimated at roughly a year and a half was completed in six weeks with a structured, spec-like workflow plus LLMs — not a small speed-up, a different class of result.
About 50% less time
Large-scale migrations reported around a 50% reduction versus the previous manual approach, driven by the same focus on structure and validation.
Mandatory validation
Shipping code is not the definition of done. These checks prove the new system matches the spec.
Contract tests
Prove the new API matches the plan — not a nearby-looking shape.
Golden tests
Check critical outputs against data you already know is good.
Traffic replay
Replay real production traffic against old and new systems and compare side by side.
Old relief
The new system finally compiles without errors.
SDD done
Proven equivalence to the spec — compiling is only the beginning.
Practice
Check your understanding
A few minutes of recall now saves rereading later.
1.The modernization trap is focusing on…
2.Intent decay means…
3.A characterization test is…
4.In spec-driven modernization, the project is done when…
Order the Strangler Fig cutover. Use the arrows to move a step, then check your order.
- 1Reroute
- 2Strangle
- 3Turn off
- 4Surround