AI can now produce code faster than most teams can decide what the code should do. That sounds like good news, and mostly it is. But it quietly moves the bottleneck.
When implementation was slow and expensive, teams could live with a fair amount of ambiguity. A requirement said “let customers recover their account”, and the developer building it discovered the awkward questions one at a time: what counts as proof of identity, what happens on the third failed attempt, whether the fraud team needs to know. Those questions were answered in corridor conversations and code review, slowly, because the code itself was arriving slowly.
A coding agent does not wait for the corridor conversation. Give it the same one-line requirement and it will change twenty files in a few minutes, answering every one of those questions itself, plausibly and without telling you. An unclear requirement used to cause a delay. Now it produces twenty files of confident misunderstanding. So faster coding raises the value of everything that tells the agent what to build: clear intent, boundaries, examples, architecture decisions and automated checks.
Spec-driven development, or SDD, is the family of practices that makes those instructions durable and reviewable. The specification stops being a document written for approval and then forgotten. It becomes an active input to planning, implementation, testing and review.
This nine-part series works through SDD practically. It covers the main approaches in use today (GitHub Spec Kit, the BMAD Method, Kiro-style requirements, design and tasks, OpenSpec, intent architecture and harness engineering) and where older disciplines such as user stories, architecture decision records, behaviour-driven development, test-driven development and API contracts still fit.
The short answer
Use SDD when the cost of building the wrong thing is greater than the cost of making intent explicit.
That sentence cuts both ways. Do not turn every one-line defect fix into a twenty-page specification. Scale the method with four things: risk, novelty, architectural reach, and the number of people and agents working on the change. A typo needs almost nothing. A change to how customers prove who they are needs a great deal.
The example we will follow
To keep the series concrete, we follow one organisation throughout. Kestrel Mutual is fictional, and all figures are illustrative.
Kestrel Mutual is a mid-sized South African insurer offering life, funeral and household cover. It has about 420,000 policyholders, around 230,000 of whom use its customer portal and app. Signing in needs a password and a one-time PIN (OTP) sent by SMS to the registered mobile number.
That works until it does not. Customers lose phones, change numbers and port to another network, and then they cannot receive the PIN. So they phone the contact centre: about 4,000 recovery calls a month, around 12 minutes each, with agents verifying identity using questions that vary from one agent to the next.
The obvious fix is a self-service recovery route. The reason it is hard is SIM-swap fraud. In South Africa, a PIN sent to a mobile number is not proof of identity on its own, because criminals can take control of the number. And an insurance account is worth taking over: change the banking details, then wait for a claim or a payout.
So Kestrel’s product owner for digital channels has a feature to deliver, known internally as SPEC-017: assisted account recovery. Customers who cannot use their registered number pass two of three approved checks, a risk engine assesses each attempt, and high-risk attempts are never reset automatically. They go to the fraud operations team instead. Kestrel’s engineers use coding agents. The question for the rest of this series is how Kestrel makes sure those agents build that feature, and not a plausible guess at it.
SDD in plain language
Imagine asking a builder:
Build me a modern three-bedroom house. Use your judgement.
A good builder will start quickly and produce something. But room sizes, budget, site constraints, materials, accessibility, security and the standard it will be inspected against are all unknown, so the builder will decide them. Some of those decisions will match what you wanted. Some will not, and you will find out when the walls are up.
A specification does not describe every nail. It establishes what success looks like, the constraints, the decisions already made, and how the result will be inspected. It leaves the builder free to be good at building.
The equivalent instruction to a coding agent, “let customers recover their account without the OTP”, invites the agent to decide what counts as proof, how many attempts are allowed, what the fraud team sees, and whether a recovered account can change its banking details straight away. Those are business decisions with fraud and privacy consequences. People should make them, and write them down, before the agent starts.
What counts as a specification?
When people hear “specification”, most picture a long requirements document. Useful specifications are usually smaller and more varied than that. A specification may include:
- the problem and the desired outcome;
- the users, and the scenarios they are in;
- functional behaviour, meaning what the system does;
- acceptance examples that show when it is working;
- business rules;
- quality requirements such as speed, availability and security;
- scope, and what is deliberately excluded;
- system boundaries;
- architecture decisions;
- data and interface contracts;
- security and privacy constraints;
- migration and compatibility needs;
- the tests and evidence that will be required;
- questions that are still unresolved.
It need not be one large document. A repository can hold linked artefacts: a constitution of rules that always apply, a product brief, a feature specification, architecture decision records (ADRs: short notes that record a significant design decision, the alternatives and the consequences), an API contract, a task list and acceptance tests. Each is small enough to review, and each points to the others. Part 3 takes a good feature specification apart, using Kestrel’s recovery spec.
Three ways a specification can relate to code
Birgitta Böckeler, writing on martinfowler.com in Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl (October 2025), separated three levels of SDD that are easy to confuse. We covered them in Why ‘vibe coding’ doesn’t scale in the enterprise; here is the short version.
| Mode | What happens to the spec | Relationship to code | Good fit |
|---|---|---|---|
| Spec-first | Written before implementation, then may be archived | Humans and agents edit the code normally afterwards | Bounded features and fixes |
| Spec-anchored | Kept current alongside the code | Reviews check code and spec together | Products under continuous change |
| Spec-as-source | People change the spec; code is generated from it | Direct code editing is restricted | Structured domains with reliable generators |
Most teams should start with spec-first or spec-anchored. Spec-as-source, where generated files are marked “do not edit” (Böckeler cites the Tessl Framework as an example), needs reliable generation, deterministic contracts and a controlled way out when the generator gets something wrong. It is worth watching, and rarely the right first step.
Kestrel chose spec-anchored for account recovery. The specification lives in the repository beside the code, and any change to how recovery behaves updates both in the same change. Recovery will be adjusted for years as fraud patterns shift, so a spec written once and archived would soon describe a system that no longer exists.
SDD is not waterfall
The obvious objection is that this sounds like waterfall: write a big document, freeze it, then build. It is not, and the difference matters.
Waterfall tries to freeze uncertain knowledge too early, then treats every discovery as a failure of the plan. Good SDD expects intent to change. What it insists on is that the change travels through a visible loop rather than hiding inside generated code.
At Kestrel, verification can end three ways. If the evidence passes, the change is released. If the code does not match the approved spec, that is an implementation gap: the work goes back to the plan and tasks, and the spec stays as it is. If testing shows the spec itself was wrong, for example the fraud team realises that an email address changed last week should not count as evidence, that is changed intent. The spec is clarified and re-approved first, and only then does the code change.
The tempting shortcut is to fix it in the code and move on. The trouble is that nobody reading the spec will ever know the rule changed, and the next agent that works from that spec will quietly put the old rule back.
When SDD earns its keep
Use more structure when:
- several systems or teams are affected;
- security, privacy, safety or regulation matters;
- data models or public contracts change;
- behaviour has many exceptions;
- agents are making broad or parallel changes;
- the codebase is unfamiliar to the people or agents changing it;
- people disagree about what “done” means;
- the feature will live for years;
- architecture drift is already visible.
Use a light flow for a typo, an isolated style fix, or an obvious dependency update in a codebase with strong automated tests.
Assisted recovery ticks almost every box on that list. It touches the portal, the identity service, the risk engine and case management. It is a fraud target. It handles identity evidence, which is personal information under POPIA. And it will live for years. That is why it sits at the top of the staircase, while a misaligned label on the same login page sits at the bottom. Treating the two the same way, in either direction, is the mistake: a twenty-page spec for the label wastes a morning, and a one-line prompt for recovery can cost a customer their payout.
What to take from this part
The bottleneck has moved from writing code to deciding what it should do. An agent resolves ambiguity instantly and silently, which is exactly why ambiguity is now expensive.
A specification is a set of linked, reviewable artefacts. Outcome, rules, examples, boundaries, decisions and evidence, rather than one long document.
Decide how each spec relates to its code. Spec-first, spec-anchored and spec-as-source are different commitments, and most teams should start with the first two.
SDD is a loop, not a freeze. Implementation gaps go back to the plan; changed intent goes back to the spec, where everyone can see it.
Scale ceremony with risk. The cost of building the wrong thing decides how much specification a change deserves.
Next in the series: Spec Kit, BMAD, Kiro, OpenSpec and the rest: the flavours of SDD.
How CloudNala can help
We help product and engineering teams decide where spec-driven development is worth the effort: sorting the change portfolio by risk, choosing which capabilities should be spec-first and which spec-anchored, and setting up the small set of linked artefacts (a constitution, a feature spec template, ADRs and acceptance examples) that lets coding agents move quickly without automating ambiguity.
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.
Plan an SDD Pilot or write to us at consult@cloudnala.co.za