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.
Four stages. One document. A team of agents. And at the end, a human who signs off.
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.
SDD isn’t tied to a language or platform. The same template carries web, backend, embedded and apps.
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.
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.
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.
| ID | Given | When | Then | Verifies |
|---|---|---|---|---|
| T68-02 | Cold start, 8 fields | first refresh | every field = target ±1e-6, no glide from zero | AC-02 |
| T68-03 | Slot taken over by a new bike | first refresh | the new bike’s value, no residue of the old one | AC-02 |
| T68-09 | 20 riders, all tied | sort | fallback to a fresh sort kicks in | AC-03 |
| T68-17a | Full room | publish | 0 bytes allocated | AC-07 |
| T68-21 | Schema constant violated | generator runs | build fails, no header | AC-09 |
5 of 24 scenarios
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.
publish() every 33 ms, ranking in the headerGenerator generates the C header from the schema. If anything drifts, the build stops.
Constraints
allocateDirect . A heap buffer makes the native call return silently without writing.publish() allocates nothing per tick, not even with a full room.Every acceptance criterion names the tests that verify it. What’s open is marked as open.
You accept against criteria you knew up front.
publish allocates nothing and stays under 10 % of the tick. T68-17a/b, -19a/b, -20exp() native vs. Kotlin on the device. open: decision neededEvery 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.
Schematic sequence, not a recording.
The agents don’t decide when they’re done. The tests do, and in the end a human.
Drop me a short note about what it’s about. The intro call is free of obligation, and the reply comes from me.