Adopting SDD: a playbook, a starting point and the failure modes

The fastest way to make an engineering organisation hate spec-driven development is to announce it. A mandate goes out, a working group produces forty templates, every team is asked to adopt them by the end of the quarter, and within a month the specifications are being generated by an agent, approved without being read and ignored by the code.

The method did not fail. The adoption did. It treated SDD as a documentation standard to roll out rather than a change in how a team works that has to prove itself on real work first.

This final part of the series is the practical one: how to start, how to choose an approach, what a minimum working system looks like, and the failure modes that catch almost every team at least once. We are still following Kestrel Mutual, a fictional South African insurer. All figures are illustrative.

Start with one real product slice

The sequence is simple: baseline one workflow, pilot one bounded feature, measure quality and effort, refine the specification and harness, scale the patterns that worked, and govern by risk. Each phase below is short on purpose.

Phase 0: baseline

Before changing anything, record how the current delivery system actually behaves:

• where requirements come from;
• the misunderstandings that keep recurring;
• defect and rework patterns;
• visible architecture drift;
• how long test feedback takes;
• how long reviews take;
• how deployment and rollback work;
• what the developer experience is like;
• how AI is already being used, officially or not, and with what risk.

Without a baseline, SDD success becomes opinion. Six months later, the enthusiasts will say it transformed delivery and the sceptics will say it added paperwork, and neither side will have evidence. Two or three of the numbers from Part 8, such as rework caused by misunderstood intent and lead time from approved intent to production, are enough to start.

Phase 1: choose a pilot

Pick work that is meaningful but bounded:

• a clear product owner;
• manageable dependencies;
• enough behaviour to test the method properly;
• no critical deadline on the first experiment;
• a measurable current pain;
• a team willing to record what it learns.

Avoid both extremes. A trivial landing page proves nothing. The equivalent of a core banking replacement carries far too much risk for a first attempt.

Kestrel is a useful illustration. Assisted account recovery, the feature this series has followed, would be a poor first pilot: it sits in the Critical risk tier, the fraud team is anxious about it and the contact centre wants it yesterday. Claim-status notifications from Part 7 would be a good one. It has a clear owner, a handful of dependencies, real behaviour to specify (consent, duplicates, failures) and a pain you can count in calls. Learn the method on that, then bring it to the high-stakes work.

Phase 2: establish the minimum system

A team needs eight things, and no more, to run the pilot:

1. a short constitution or set of engineering principles;
2. one feature-spec template;
3. one ADR template (an architecture decision record: a short note of a significant decision and its consequences);
4. a task-planning method;
5. acceptance and CI gates;
6. repository instructions for agents, such as an AGENTS.md file;
7. an approval matrix by risk;
8. a rule for how changes are made and specifications archived.

One template for each, not a library. The templates will be wrong in ways the pilot reveals, and one template is cheap to fix.

Phase 3: run the loop

1. Draft the intent.
2. Identify unknowns and contradictions.
3. Review with product and domain owners.
4. Plan the architecture and record durable decisions.
5. Break the work into bounded tasks.
6. Implement in isolated changes.
7. Verify automatically.
8. Review against the original specification.
9. Release progressively.
10. Update durable intent from what was learned.

Step 8 is the one that quietly disappears under deadline pressure, because reviewing against the diff feels like enough. It is not. Code can be clean, tested and wrong.

Phase 4: scale

Scale reusable capabilities rather than paperwork:

• shared constitution sections;
• a domain glossary;
• architecture rules and linting;
• contract templates;
• test harnesses;
• approved agent tools and permissions;
• evaluation and observability;
• training and coaching;
• metrics and communities of practice.

Let teams tailor within boundaries. Standardise the evidence and the control outcome, not every sentence.

Choosing a starting approach

Part 2 described the main approaches in detail. The practical question is which to reach for first, and the honest answer depends on your situation rather than on which tool is most talked about this month.

Two terms in the last row need explaining. An invariant is a condition that must always hold, such as “a policy never has two active banking-detail records”. A property test generates many random inputs and checks that an invariant survives all of them, which catches the cases nobody thought to write an example for.

These approaches combine. A regulated brownfield product might reasonably use change deltas, ADRs, contract tests and risk gates together. Do not combine them merely to collect terminology. Every added practice should answer a problem the team actually has.

The failure modes

Almost every team adopting SDD meets several of these. Naming them early makes them easier to catch.

The generated specification nobody read. An agent expands a short idea into polished text, and the team approves how it looks rather than what it means. Control: named human approval of the outcome, rules, constraints and open questions.

Template worship. Every field is completed, including irrelevant ones, while one material ambiguity stays unresolved. Control: tailor templates and review for risk coverage, not completeness.

A spec too close to the code. The specification prescribes classes, methods and file names without explaining behaviour or trade-offs. Control: keep outcome and observable behaviour separate from the technical plan.

A spec too vague. “Build a scalable, secure, user-friendly portal.” Control: scenarios, boundaries, examples, quality measures and acceptance criteria, as in Part 3.

The frozen spec. The team learns during implementation but leaves the approved document unchanged. Control: a visible amendment workflow and versioned decisions.

Everything is global context. Every task loads every standard, document and piece of history. Control: layered intent and retrieval of only the relevant context, as in Part 4.

The agent reviews its own work. The same context and model produce the design, the code and the approval. Control: deterministic checks, independent review and human accountability.

Parallelise first, design later. Several agents change shared interfaces at the same time. Control: settle boundaries and contracts before starting parallel tasks.

Tests that match the implementation, not the intent. An agent writes code and tests that agree with each other and both misunderstand the requirement. Control: derive acceptance examples independently, from the approved behaviour.

The spec graveyard. Specifications remain after delivery and nobody knows whether they are still authoritative. Control: declare whether each area is spec-first, spec-anchored or spec-as-source, and archive accordingly.

Tool lock-in. Product knowledge exists only in one vendor’s agent sessions. Control: keep durable intent, ADRs, contracts and evidence in the repository.

Process inflation. A small team spends more effort operating SDD than learning from its users. Control: scale the ceremony by risk and use quick paths for small changes.

The agent reviewing its own work is the most dangerous of the twelve, because it looks exactly like diligence. The pull request has a review, the review is thorough, and nobody independent ever checked it.

A reference operating model

For teams that want a single page to work from, this is the model the series has been building towards.

The artefact stack

Recommended checkpoints

Definition of ready for agent implementation

• The problem and outcome are explicit.
• Scope and exclusions are clear.
• Examples include success, failure and boundary cases.
• Unknowns are resolved or deliberately deferred.
• Relevant architecture and contracts are identified.
• The task is small enough for isolated review.
• Required tools and permissions are available.
• Tests or acceptance evidence are defined.
• Rollback and migration are addressed where needed.
• A human owner accepts the task.

Definition of done

• Code and configuration implement the approved behaviour.
• Tests pass at the required levels.
• Security and policy checks pass.
• The spec and ADRs reflect the final decisions.
• Contracts remain compatible, or the migration is approved.
• Observability and support material exist.
• Acceptance evidence is retained.
• No unexplained scope expansion remains.
• The human owner approves release.

Sources and further reading

The tools in this ecosystem change quickly. Descriptions in this series were checked against official documentation on 14 September 2026; verify current commands and versions before you implement.

• GitHub Spec Kit repository and documentation
• GitHub blog: spec-driven development with AI (September 2025; command names have changed since)
• BMAD Method repository and documentation
• Kiro specs documentation
• OpenSpec repository and site
• Intent-driven development resource by Hari Krishnan (features OpenSpec)
• OpenAI: Harness engineering (February 2026)
• Birgitta Böckeler: Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl
• EARS: Easy Approach to Requirements Syntax
• RFC 2119: key words for requirements and RFC 8174
• C4 model
• Architecture Decision Records
• OpenAPI Specification
• AsyncAPI Specification

“Intent architecture” and “harness engineering” are emerging umbrella terms rather than governed standards. The definitions in this series are architectural interpretations of current public practice. Define your own vocabulary in your own operating model.

The final principle

AI coding changes the economics of implementation. It does not remove the need for product judgement, architecture, engineering discipline or accountability. The organisation that specifies clearly, builds a good harness and learns from runtime evidence will outperform the organisation that merely generates more code.

What to take from this part

Adopt on real work, not by mandate. One bounded pilot teaches more than forty templates.

Baseline before you begin. Without before-and-after evidence, the verdict on SDD is opinion.

Build the minimum system and scale what worked. Standardise evidence and control outcomes, not every sentence.

Choose an approach by situation. Combine practices only where each solves a real problem.

Watch for the agent reviewing its own work. It is the failure mode that looks most like diligence.

That completes the series. To start again from the beginning, read Part 1: The code is no longer the first hard problem, or browse all nine parts on the series page.

How CloudNala can help

We help teams run their first spec-driven pilot properly: taking a baseline, choosing a bounded slice of real work, setting up the minimum system of principles, templates, harness and risk gates, and measuring the result honestly before anything is scaled. CloudNala helps teams turn business intent, architecture and delivery controls into an AI-assisted engineering system that can move faster 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