Code is no longer the bottleneck.

The question is whether the right thing gets built. And whether anyone still understands it a year from now.

SDD answers both with one document: a precise, versioned specification. Problem, architecture, constraints, tests, acceptance. Before the first line of code is written.

Four stages. One document.

SDD isn’t tied to a language or platform. The same template carries web, backend, embedded and apps.

Walkthrough: an example from an Android/Kotlin project

A live platform for indoor cycling races. The excerpts come from two specifications of this project: Spec 12 (architecture) and Spec 68 (data path). Names have been removed.

  1. Vision
  2. Microspecs
  3. Build
  4. Proof

Vision. Problem first.

Goal, problem, architecture. Versioned like source code. The code follows from it, not the other way round.

Before money goes into code, it’s settled what gets built and how success is measured.

Excerpt from Spec 12: the Stage interface with its shared base class, the Theater API and the fixed ordering of replaceScene, as code with explanations.
Interfaces, fixed before any code exists. Anonymized.
Spec 12, Stage interface and Theater API section, full size.

Microspecs. Every requirement becomes a test.

The spec breaks down into numbered units. Each with test scenarios built from real values. Result: green or red.

Whether something is done isn’t a gut call.

IDGivenWhenThenVerifies
T68-02Cold start, 8 fieldsfirst refreshevery field = target ±1e-6, no glide from zeroAC-02
T68-03Slot taken over by a new bikefirst refreshthe new bike’s value, no residue of the old oneAC-02
T68-0920 riders, all tiedsortfallback to a fresh sort kicks inAC-03
T68-17aFull roompublish0 bytes allocatedAC-07
T68-21Schema constant violatedgenerator runsbuild fails, no headerAC-09

5 of 24 scenarios

Build. Against the spec, not the prompt.

Agents write the code, test-first. The constraints live in the spec, not in one developer’s head.

No knowledge gets lost in chat histories. The spec is the documentation.

  1. Radio gatewayUDP multicast, data from every bike
  2. Receiverone thread: check sender, parse, write slot
  3. Buffer poolpublish() every 33 ms, ranking in the header
  4. Smoothing & sortingKotlin reference, C accelerator
  5. Displayseveral readers, one data state

Generator generates the C header from the schema. If anything drifts, the build stops.

The data path, simplified. Highlighted: what the spec changes.

Constraints

  • The Kotlin implementation stays forever: as the readable reference and as the test oracle.
  • Native buffers must be allocateDirect . A heap buffer makes the native call return silently without writing.
  • publish() allocates nothing per tick, not even with a full room.
  • A single writer, the event-loop thread. No extra locks.

Proof. Only what’s proven gets accepted.

Every acceptance criterion names the tests that verify it. What’s open is marked as open.

You accept against criteria you knew up front.

  • AC-01 Native smoothing matches the Kotlin reference to within 1e-4. T68-01, -05, -06
  • AC-07 publish allocates nothing and stays under 10 % of the tick. T68-17a/b, -19a/b, -20
  • AC-09 Schema drift breaks the build, not the display. T68-21
  • AC-11 Tolerance for exp() native vs. Kotlin on the device. open: decision needed

A team of agents. A human who signs off.

Every agent has exactly one job. None can fulfil a spec on its own. The specification is what coordinates them.

Animation: the domain agent settles the terminology with the architect. The architect breaks the specification into microspecs and hands them to three workers. The workers go test-first: test red, code, test green. Results go to the reviewer and the security agent; each sends one finding back, and the workers fix it with a new test. At the end a human reviews and signs off. The steps are listed alongside.

  1. Domain ↔ Architect terminology settled, glossary in place
  2. Spec → Architect Vision spec 12: goal, problem, architecture, scenarios
  3. Architect breaks it into microspecs with dependencies
  4. Architect → Workers 12.1, 12.2, 12.3 in parallel
  5. Workers, TDD test red → code → test green, scenario by scenario
  6. Workers → Reviewer, Security done, all tests green
  7. Reviewer, Security check against the spec and for vulnerabilities
  8. Security → Worker Finding 12.2: unvalidated input
  9. Reviewer → Worker Finding 12.3: duplicated responsibility, SoC
  10. Workers, TDD new test red → fix → green
  11. Workers → Reviewer, Security fixed
  12. Reviewer, Security → Human report: criterion → test → result
  13. Human reviewed against the acceptance criteria, signed off

Schematic sequence, not a recording.

  • Domain knows the business language and settles terms before anything is planned. Doesn’t plan.
  • Architect reads every spec, breaks it into microspecs, plans and delegates. Writes no code.
  • Worker work test-first: the failing test first, then the code, one microspec at a time. Make no architecture decisions.
  • Reviewer checks against the spec: test coverage, architecture, DRY, SoC, KISS. Doesn’t implement.
  • Security checks for vulnerabilities, guided by OWASP. Doesn’t implement.
  • Human judges the result against the acceptance criteria and signs off.

The agents don’t decide when they’re done. The tests do, and in the end a human.

Should your next project be built this way?

Drop me a short note about what it’s about. The intro call is free of obligation, and the reply comes from me.