SDCourse overview

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. 1

    Origin

    The weird line of code exists for a reason — a business rule, a lawsuit, a customer exception.

  2. 2

    People leave

    Original developers move on. The oral history of why the system works this way leaves with them.

  3. 3

    Docs go stale

    Wikis and comments stop matching production. The only remaining “spec” is the running code.

  4. 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. 1

    Map what it does today

    The good, the bad, and the ugly — observed behaviour, not hoped-for design.

  2. 2

    Write characterization tests

    A digital straitjacket that locks current behaviour so you do not break something important by accident.

  3. 3

    Translate into spec.md

    Structured intent: invariants, scenarios, and a do-not list — the why, written down.

What goes in spec.md

Invariants

When this happens, the system shall do that — no fuzzy adjectives, no tribal knowledge.

Scenarios

Happy path, weird edge cases, and how errors are handled — the behaviour you actually found.

Do-not list

Defence against scope creep: do not change this business rule; do not add that new feature during the cutover.

Living specs & executable guardrails →

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. 1

    Draft spec

    Read old code to propose the first spec.md — humans recover and freeze intent.

  2. 2

    Plan & contracts

    Turn the finished spec into an architectural plan and data contracts.

  3. 3

    Task the work

    Break the plan into pull-request-sized, independently verifiable tasks.

  4. 4

    Implement with guardrails

    Build each task against the spec and contracts — not against a demo script.

Loading Workflow pipeline…
Expert AI crew (Section 6 · Lesson 4) →

What this looks like in practice

Airbnb

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.

Google

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.

Verification gates (Section 6 · Lesson 2) →

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.

0 of 4 answered
  1. 1.The modernization trap is focusing on…

  2. 2.Intent decay means…

  3. 3.A characterization test is…

  4. 4.In spec-driven modernization, the project is done when…