Every large organisation that adopts a new delivery method eventually produces the same report. It shows how many teams have adopted the template, how many specifications were written this quarter and what percentage of pull requests link to one. The numbers go up. Nobody can say whether the software is any better.
Spec-driven development is especially vulnerable to this, because it produces documents, and documents are easy to count. Add coding agents that can generate a polished forty-page specification in a minute, and the count becomes meaningless almost overnight.
The question governance should ask is different: do the intent, the design, the code and the runtime evidence agree, and can we show it? This part is about answering that question at enterprise scale without drowning teams in paperwork.
We are still following Kestrel Mutual, a fictional South African insurer. All figures are illustrative. By this point several Kestrel squads are working this way, with coding agents in the loop, and the internal audit team has started asking the kind of questions that a regulator or a court might ask later.
Every durable artefact needs a named owner
A specification without an owner is a document that will be wrong within a year, and nobody will notice. Ownership has to be explicit, and so does the event that should make the owner look at it again.
| Artefact | Accountable owner | Review trigger |
|---|---|---|
| Product intent and KPI | Product owner | Strategy or outcome change |
| Domain glossary and rules | Domain owner | Rule or language change |
| Engineering constitution | Engineering leadership | Policy or platform change |
| Architecture boundary | Architecture owner | New dependency or responsibility |
| ADR | Decision owner | Assumption invalidated |
| Feature spec | Product squad | Behaviour or scope change |
| Interface contract | Provider and consumers | Version or compatibility change |
| Acceptance evidence | QA, product or risk, as applicable | Every implementation change |
| Runbook and SLO | Service owner | Operational or failure change |
A few terms, for readers who have not met them. An ADR, or architecture decision record, is a short note that captures a significant design decision, the options considered and the consequences. An interface contract is the precise, machine-readable description of how two systems talk, often written in OpenAPI for web APIs or AsyncAPI for events. An SLO, or service level objective, is the reliability target a service is run against, such as 99.9% availability in a month.
The review trigger column is the part most organisations leave out, and it is the part that keeps the table honest. At Kestrel, the fraud and identity operations lead owns the domain rules for account recovery. When fraud operations decided to add a new evidence check, that decision was the trigger to update the specification, not a detail for engineering to discover in a support ticket.
Traceability without an expensive database
Traceability means being able to follow a thread from a business outcome through to the code and the evidence that it works, and back again. In regulated industries it is often treated as a tooling problem, solved with a large requirements management product that nobody enjoys updating.
For most teams it does not need to be. Stable identifiers and links kept in version control are usually enough. Here is one thread from Kestrel’s assisted account recovery feature:
OUT-03 -> SPEC-017 -> ADR-024 -> TASK-017-04 -> PR-481 -> TEST-REC-12 -> SLO-ID-02
Read left to right, the chain says: the outcome of reducing recovery calls without increasing account takeover (OUT-03) led to the assisted recovery specification (SPEC-017), which relies on the decision that identity decisions stay in the identity domain (ADR-024). One task from that work added the case-creation adapter (TASK-017-04), delivered in pull request 481, proved by an acceptance test (TEST-REC-12) and measured in production by an identity service objective (SLO-ID-02). The arrow back to the outcome is what stops the chain being a filing system: runtime evidence tells the product owner whether the outcome is actually being achieved.
The chain must be able to answer three questions for any piece of code:
- Why does this code exist?
- Who approved the behaviour?
- What proves it works?
If an auditor, a new engineer or a coding agent cannot answer those from the repository, the traceability is not working, however many links it has.
Gates scaled to risk
Not every change deserves the same scrutiny. A single approval process for everything either slows trivial changes to a crawl or waves dangerous ones through. Risk tiers make the level of control explicit.
| Tier | Example | Required control |
|---|---|---|
| Low | Copy, isolated style or non-functional refactor | Mini-spec, tests and peer review |
| Medium | Business feature inside one bounded service | Reviewed spec, design, acceptance and normal CI |
| High | Public API, identity, payment, personal data or cross-system workflow | Architecture/security review, contracts, rollback and operational evidence |
| Critical | Safety, regulated decision, production infrastructure or irreversible data change | Named accountable approvers, independent validation, staged release and recovery proof |
CI, in the Medium row, is continuous integration: the automated build and test run on every change. Independent validation, in the Critical row, means someone who did not build the change checks it, with a method they chose.
Kestrel placed assisted account recovery in the Critical tier, even though “identity” appears in the High row. The reasoning is worth copying. A wrongly completed recovery hands a customer’s account to someone else, and at an insurer that someone can change the banking details a payout will go to. Rolling back the code does not return the money. The tier is set by the harm if the change is wrong, not by which keyword the change happens to contain.
One rule applies to every tier: do not allow an agent to classify the risk of its own change. An agent that decides its own work is Low risk has also decided how much review it gets. Tiering is a policy decision, applied by rules and confirmed by a person. Part 5 shows how each tier maps to the verification a harness runs.
Put security in the specification
Security added at the end is security that someone has to argue for against a deadline. Written into the specification, it becomes part of what “done” means. A specification for any High or Critical change should state:
- the data classification and what the data may be used for;
- identities and authorisation: who and what may do each action;
- trust boundaries: where data crosses from one level of trust to another;
- threat assumptions: what the design defends against, and what it does not;
- secrets and key handling;
- input and output validation;
- dependency and supply-chain controls;
- logging without leaking sensitive data;
- abuse, rate and resource limits;
- human approval for privileged or irreversible actions;
- the security acceptance evidence.
For South African organisations this is also where the obligation to secure personal information under POPIA stops being a policy statement and becomes something testable. “Raw selfie images are deleted after the approved retention period” is a line in Kestrel’s recovery specification with a test behind it. “We take privacy seriously” is not. Sector regulators in financial services increasingly expect evidence of IT and cyber controls rather than assurances; a specification with security acceptance evidence is where that evidence starts. For a practical view of what production trust requires, see the trust checklist for AI-built software.
Specification and code change together
The unit of change should include everything a reviewer needs to judge it: the specification update, the code, the tests, any migration and the operational documentation. When they arrive in one pull request, a reviewer can see the intent and the implementation side by side. When the spec is updated in a wiki three weeks later, nobody reviews the two together, and they drift.
For systems that are spec-anchored, where the specification is meant to stay current with the code, one rule does most of the work:
Block a merge when observable behaviour changes without a corresponding spec update, or require the author to declare explicitly that the change does not alter behaviour.
The declaration matters. It turns a silent omission into a visible claim that a reviewer can challenge. At Kestrel it is a required checkbox in the pull request template, and changes under the recovery flow’s code paths also require review from the owners of the specification folder. Neither is sophisticated. Both make drift a decision someone has to take on purpose.
Measure the right things
The easy metrics are the wrong ones: lines of generated code, number of specifications written, percentage of template fields completed. They reward volume, and agents make volume free.
Track these instead:
- clarification questions resolved before implementation;
- implementation rework caused by misunderstood intent;
- escaped defects linked to a missing or wrong specification;
- lead time from approved intent to production;
- acceptance-test pass rate;
- architecture and security exceptions;
- drift between specification and code;
- review effort;
- agent retry and failure rate;
- cost per accepted change;
- rollback and incident rate;
- the time it takes a new team member, or an agent, to make a safe change.
The first two are the heart of it. If SDD is working, questions move earlier and rework caused by misunderstanding falls. If the first number goes up and the second does not come down, the specifications are being written but not read. For agent cost and quality metrics that pair well with these, see the four weekly AI engineering metrics.
Keep intent independent of any one model or tool
Coding models, IDEs and agent products will change several times over the life of a system that matters. Durable intent should outlive all of them. Keep specifications, contracts, decisions, tests and operating evidence in open, readable formats, in the repository, where practical.
Tool-specific commands and configuration can live in a thin adapter layer: the folder of prompts and slash commands a particular tool needs. If Kestrel changed coding agents next year, it should lose that folder and nothing else. The product should not lose its institutional knowledge when a model, an IDE or an agent changes.
What to take from this part
Govern agreement, not volume. The test is whether intent, design, code and runtime evidence agree, not how many templates were filled in.
Give every durable artefact an owner and a review trigger. Without a trigger, ownership is a name on a page.
Traceability can be plain identifiers in version control. It works when it answers why the code exists, who approved it and what proves it.
Set the risk tier by the harm if the change is wrong. Never let an agent classify its own risk.
Change the spec and the code in the same unit. Where behaviour changes without a spec update, make the author say so explicitly.
Next: Part 9: Adopting SDD: a playbook, a starting point and the failure modes.
How CloudNala can help
We help engineering and risk leaders design governance that checks evidence rather than paperwork: an ownership model for durable artefacts, a lightweight traceability convention that lives in the repository, risk tiers with gates matched to them, and pull-request and CI rules that keep specifications and code moving together. It is designed to satisfy audit without slowing the teams that are already doing the right thing.
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