Ask a coding agent to "add a discount for loyalty customers" and it will produce something. It might be exactly what you meant. It might apply the discount before tax instead of after. It might not handle the case where a loyalty customer also has a voucher. It will look plausible either way, because a coding agent always produces something — the question is never whether it generates code, it's whether that code encodes your intent or a statistically reasonable guess at it.
This is Part 3 of our series on Chris Ford's O'Reilly Early Release book Agentic Engineering at Scale. Part 1 set out the harness framework — Guides, Guards, Checks, Sensors. This piece is about the normative half of that framework — Guards and Checks — and the discipline built around them: spec-driven development.
Conversational prompting under-constrains the solution
"Vibe coding" — steering an agent through informal back-and-forth dialogue — genuinely works well when you don't have strong opinions about most of the details. That describes a lot of prototyping. It describes very little production enterprise software.
The problem isn't that the agent is unreliable. It's structural: when you leave a decision unspecified, the agent doesn't leave a gap — it samples from the space of plausible solutions, shaped by the aggregate of its training data rather than by your specific context. Sometimes that sample matches what you needed. Sometimes it's what everyone calls a hallucination. Both are the same kind of event — output without a foundation in your actual intent — and whether you're happy with the result is often just luck.
Spec-driven development (SDD) is the discipline of replacing that luck with structure: encoding your expectations in artefacts a coding agent can respect, so it's narrowing toward a solution you'd actually sign off on, rather than sampling freely.
A spec is not a Markdown file
The instinct when people first hear "spec-driven development" is to picture a requirements document. That's part of it, and also the weakest part of it on its own. Natural language faithfully conveys the ambiguity of human conversation — which is also exactly its weakness as a specification. It's imprecise, and hard to mechanically compare against a solution.
Effective SDD treats a specification as plural — a combination of complementary artefact types, each covering ground the others don't:
- Natural-language requirements — necessary for intent and context, weak on precision.
- Examples and tests — precise and intelligible, but a finite set of examples can't fully specify a general rule. There are infinitely many curves through any set of points on a graph; good test design is the art of choosing examples that pin down the ones that matter.
- Architecture decision records (ADRs) — capture the why behind a standing decision, so an agent (or a new team member) understands not just what was chosen but what trade-off it was resolving.
- Contracts and schemas — describe integration boundaries precisely. In an agentic context, they're a Pareto-efficient form of governance: a schema gives an agent real guidance without dictating every implementation detail underneath it.
- Invariants and assertions — runtime checks that a condition must hold. Coding agents, unlike experienced engineers, don't reliably notice on their own when a program has drifted into an invalid state — a clear assertion with a useful error message gives them a signal to correct course on.
Think of it as James Reason's Swiss cheese model of risk management, adapted: no single spec type has to be complete, because the next layer covers its gaps. What a spec stack has to be, that Reason's safety model doesn't, is selective — it has to admit every good solution and exclude only the bad ones, not just block everything indiscriminately.
Three ways specs and code can relate
Not every team should be doing the same kind of spec-driven development, and conflating them causes real confusion in how teams evaluate SDD tooling. Birgitta Böckeler's distinction, which the book adopts, is genuinely useful:
Spec-first — the spec is a planning artefact, discarded once the change lands; the code is what's actually maintained. This is the lightest-weight form, close to a well-structured planning conversation before you code. Most teams using an agent's "plan mode" are already doing this, whether they call it SDD or not.
Spec-anchored — both the spec and the code persist and are kept in sync over time. This is more disciplined and more valuable for constitution-level decisions — the standing rules that should hold across every future change — but genuinely harder to sustain, because now you're maintaining two artefacts instead of one.
Spec-as-source — the spec is what's maintained; the code is treated as disposable, regenerated when the spec changes. This is the boldest interpretation and, honestly, still more aspirational than proven at enterprise scale in 2026. Worth knowing about. Not yet worth betting a production system on wholesale.
A useful way to decide which applies to a given change is to ask how long the underlying decision needs to live. A one-off bug fix is naturally spec-first — the spec is disposable because the change is. A cross-cutting architectural decision is naturally spec-anchored — you'll want to check future changes against it for years. Most feature work sits in between, and the honest answer is "it depends," which is itself useful: if you claim to be spec-anchored but never actually update the spec, you're really doing spec-first and should stop pretending otherwise.
Decision specs: the fix for both failure modes
Two problems recur once you're running mixed-method SDD in practice: ambiguity (the spec doesn't say enough, so the agent fills gaps stochastically) and compositional difficulty (your different spec artefacts — a state machine here, an invariant there — quietly contradict each other, and nobody notices until the agent picks one arbitrarily).
The book's answer is the decision spec: before generation starts, have the agent (or the team) explicitly surface and pin down the accidental-complexity decisions the spec leaves open — the ones with no "correct" answer from the business's point of view, but that still need to be made consistently. This isn't about specifying every detail; over-specifying a solution excludes good implementations just as surely as under-specifying invites bad ones. It's about making the arbitrary choices explicit, so they don't get silently re-rolled on the next regeneration and so a human can actually see, and challenge, the reasoning if it looks wrong.
What "good" looks like in a South African engineering team
For teams we work with — many carrying compliance obligations under POPIA, sector-specific regulation in banking and insurance, or public-sector procurement scrutiny — the practical starting point is rarely "adopt an SDD framework." It's smaller and more immediate:
- Write down the two or three architectural decisions your team keeps re-litigating in code review, as short ADRs an agent can actually be pointed at.
- For the business rules that genuinely matter — pricing, tax, eligibility, compliance thresholds — capture the two or three examples that would catch a wrong implementation, not an exhaustive test matrix.
- For any integration boundary you don't own, write the contract down explicitly rather than letting it live only in a Postman collection someone remembers exists.
- Be honest about which of your specs are meant to persist and which are disposable planning aids — and don't let the disposable ones quietly become the only record of a decision that actually needed to last.
None of this requires buying a framework. Frameworks — Kiro, Spec Kit, and others emerging through 2026 — give you structure, discoverability and workflow conventions for free, which is genuinely valuable. But SDD itself is a discipline, not a product category. You can practise it with nothing more than a well-organised AGENTS.md, a folder of ADRs, and the willingness to say "no, that's not specified precisely enough" before a coding agent starts generating.
How CloudNala can help
CloudNala helps engineering teams build a working spec layer — the right mix of ADRs, contracts, examples and decision records for how your team actually operates — so coding agents produce work you can trust without re-litigating every output by hand.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Book an AI Readiness Workshop or write to us at consult@cloudnala.co.za