Spec-Driven Development
Make intent precise. Make delivery verifiable.
Translate a rough idea into an executable specification that guides an AI agent from implementation to verified behavior.
When an AI agent writes the implementation, someone still has to define what “correct” means. Practice the discipline of specifying behavior, constraints, non-goals, and evidence before delegating the work.
Your learning path.
01Beyond vibe codingWeek 1 · ≈4 hours+
Explore why plausible code is not the same as a correct system, and where spec-driven development sits among the methods you already use.
Objectives
- Explain the intent gap and identify it in a real request.
- Place spec-driven development relative to TDD, BDD, ATDD, DDD, contract-first and model-driven approaches.
- Judge when a lightweight specification is sufficient and when it is not.
Topics
- Intent → specification → agent → implementation → verification
- What “driven” means in each method, and why they compose rather than compete
- What humans own: problem framing, architecture, and decisions
- The economics: where the hour goes before and after assisted development
- When lightweight specifications are enough — and when they are over-engineering
Concepts
Vibe coding
Generating code from an informal prompt and accepting it on the strength of how plausible it looks, with no written definition of correct.
Intent gap
The distance between what a stakeholder meant and what the request actually said. A model closes it by guessing, confidently.
Executable specification
A behaviour description precise enough that an agent can implement from it and a test suite can be derived from it without further guessing.
Exercise
Audit an ambiguous prompt and document its missing decisions.
Deliverable
An audit listing every decision the prompt silently delegated, and who should have made each one.
02Define the problemWeek 1 · ≈4 hours+
Write a brief that exposes assumptions before they become code.
Objectives
- Separate a problem statement from a preferred solution.
- State non-goals with the same care as goals.
- Convert open questions into either a decision or a recorded assumption.
Topics
- Users, jobs, observable outcomes, and success measures
- Scope, non-goals, constraints, and dependencies
- Solution smuggled in as requirement: how to spot it
- Resolving open questions and recording assumptions
- Sizing a slice so that a wrong answer stays cheap
Concepts
Non-goal
A behaviour deliberately excluded from scope, written down so neither a reviewer nor an agent quietly reintroduces it.
Observable outcome
A change in the world that someone outside the system could notice — the only kind of success worth specifying.
Slice
A bounded unit of specification and delivery, small enough that discarding it is not painful.
Exercise
Produce a problem brief with measurable success criteria.
Deliverable
A problem brief with users, jobs, success measures, non-goals and a recorded assumptions list.
Lesson material is being prepared for this module.
03Specify behaviorWeek 2 · ≈5 hours+
Describe what must happen, what must never happen, and how anyone will know.
Objectives
- Write acceptance criteria that two reasonable people cannot disagree about.
- Specify failure behaviour as deliberately as the happy path.
- Cover authorisation, privacy and accessibility as requirements rather than afterthoughts.
Topics
- Happy paths, edge cases, and failure states
- Given–when–then examples and acceptance criteria
- The binary-and-observable test for a criterion
- Authorization boundaries, privacy, and accessibility
- Splitting a compound requirement hiding in one sentence
Concepts
Acceptance criterion
A single, observable, binary statement about the system. If two reasonable people can disagree about whether it passed, it is not yet one.
Failure behaviour
What the system does when the happy path ends. It is behaviour, and it is specified, not discovered.
Compound requirement
Two obligations wearing one sentence. Splitting them is often the highest-value edit in a review.
Exercise
Write a behavior specification for a small registration flow.
Deliverable
A behaviour specification with happy path, edge cases, failure states and binary acceptance criteria.
Lesson material is being prepared for this module.
04Contracts and architectureWeek 2 · ≈4 hours+
Define the interfaces that let independent pieces — and independent agents — fit together.
Objectives
- Express data models and validation rules as contracts an implementer cannot misread.
- Specify state transitions, concurrency and idempotency explicitly.
- Record architectural decisions with their trade-offs and rejected alternatives.
Topics
- Data models, API contracts, and validation rules
- State transitions, concurrency, and idempotency
- Uniqueness, ordering and time as specification problems
- Architecture decision records and explicit trade-offs
- Designing contracts that let two agents work in parallel
Concepts
Data contract
The agreed shape, constraints and invariants of the data crossing a boundary — the part an agent should never be left to invent.
State transition table
An exhaustive statement of which states may follow which, which turns “it should not happen” into “it cannot”.
Architecture decision record
A dated note of a decision, its alternatives and its trade-offs, so a later change is informed rather than accidental.
Exercise
Create a data contract and a state-transition table.
Deliverable
A data contract, a complete state-transition table, and one architecture decision record.
Lesson material is being prepared for this module.
05Delegate to an agentWeek 3 · ≈5 hours+
Translate the specification into work an agent can complete safely, and review its first attempt.
Objectives
- Assemble a task pack with context, constraints, permitted actions and a definition of done.
- Place review checkpoints before anything irreversible.
- Review an agent implementation against the specification rather than against intuition.
Topics
- Task boundaries and the definition of done
- Providing context, constraints, and permitted actions
- The pre-delegation checklist
- Checkpoints, review gates, and escalation rules
- Reading an agent implementation for what the spec did not say
Concepts
Task pack
The bounded unit of work handed to an agent: context, constraints, permitted actions, definition of done, and review checkpoints.
Definition of done
The evidence that ends the task. It names artefacts and checks, never effort.
Permitted actions
An explicit list of what may be created, changed or deleted, so over-reach is a violation rather than a surprise.
Exercise
Prepare an agent task pack and review its first implementation.
Deliverable
A task pack, the resulting implementation, and a review noting every gap the specification left open.
Lesson material is being prepared for this module.
06Verify against the specificationWeek 3 · ≈4 hours+
Use evidence to decide whether a requirement has been met — and treat missing evidence as a finding.
Objectives
- Build a traceability matrix from requirements to concrete evidence.
- Design positive, negative, boundary and regression cases for a requirement.
- Detect implementation drift and incomplete evidence in review.
Topics
- Requirement-to-test traceability
- Positive, negative, boundary, and regression cases
- Tests derived from the requirement versus tests derived from the diff
- Reviewing implementation drift and incomplete evidence
- Reviewing a deliberately flawed patch against a specification
Concepts
Traceability matrix
A mapping from every critical requirement to the specific evidence that settles it. An empty cell is a blocking finding.
Boundary case
The test at the exact edge of a rule — the deadline instant, the limit value — where specifications most often turn out to be ambiguous.
Implementation drift
The gap that opens when code evolves and the specification does not.
Exercise
Build a traceability matrix and test a deliberately flawed patch.
Deliverable
A complete traceability matrix plus a review of the flawed patch identifying each unmet requirement.
Lesson material is being prepared for this module.
07Change without losing intentWeek 4 · ≈4 hours+
Keep the specification useful after the first implementation — the part that separates this from waterfall.
Objectives
- Handle a change request with impact analysis and a versioned decision.
- Keep specification, tests and code aligned as all three move.
- Run a repeatable delivery and review protocol with a team.
Topics
- Change requests, versioned decisions, and impact analysis
- Keeping code, tests, and specification aligned
- Deprecating a requirement without erasing its history
- Specification review as a team practice
- A repeatable delivery and review protocol
Concepts
Change request
An amendment to the specification with its impact analysis attached, which makes change visible rather than silent.
Specification version
A dated, reviewable state of the spec, so “what did we agree?” has an answer.
Alignment debt
The accumulated distance between what the spec says, what the tests check, and what the code does.
Exercise
Complete the capstone and a review explaining one specification change.
Deliverable
Capstone specification, implementation, verification matrix, and a versioned change record.
Lesson material is being prepared for this module.
Who this is for +
- Developers who already use AI coding tools and want more control.
- Technical leads responsible for architectural decisions and quality.
- Product-minded engineers translating intent into implementation.
Before you begin +
- Experience building or reviewing a small software application.
- Familiarity with Git, APIs, and basic testing concepts.
- Access to a coding assistant; no specific vendor is required.
What you will learn +
- Separate a problem statement from a preferred solution.
- Specify observable behavior, constraints, and explicit non-goals.
- Capture edge cases, failure states, and data contracts.
- Divide a specification into bounded agent tasks.
- Trace each important requirement to verification evidence.
- Manage specification changes without losing architectural intent.
Applied assignments +
Problem & behavior brief
Scope, non-goals, user scenarios, and measurable acceptance criteria.
Agent implementation pack
Contracts, task boundaries, permitted actions, and review checkpoints.
Verification matrix
A mapping from every critical requirement to concrete test evidence.
Your capstone project +
Specify and direct a registration service
Capstone brief +
Start with an ambiguous course-registration request. Define its behavior, data contracts, duplicate-payment handling, and failure states. Direct an AI agent to implement a bounded slice, then prove the result against your specification.
Assessment +
A 75-minute scenario exam: repair an incomplete specification, identify conflicting constraints, review an agent task plan, and design verification evidence.
What you will produce +
- Specification template
- Acceptance-criteria worksheet
- Agent task-pack template
- Requirement-to-test matrix
The method, explained +
Kicker
THE METHOD, EXPLAINED
What is spec-driven development?
Spec-driven development is a way of building software in which a written specification — not a prompt, a ticket, or a conversation — is the primary artefact that work is produced from and judged against.
- You write down the behaviour the system must exhibit, the constraints it must respect, the things it must deliberately not do, and the evidence that will prove each of those claims. Only then is the implementation produced — increasingly by an AI coding agent rather than by hand. The specification is what the agent reads, what the reviewer reviews, and what the tests are traced back to.
- The shift matters because generation is no longer the bottleneck. A capable model can produce a plausible implementation of almost anything in minutes. What it cannot do is decide what “correct” means for your organisation, your users, your regulator, or your existing architecture. That decision stays with a human, and a specification is how that decision is recorded in a form an agent can act on and a team can argue with.
- Spec-driven development is therefore less a new technology than a relocation of effort. The hours you no longer spend typing implementation move upstream into problem definition and downstream into verification. Teams that skip that relocation experience AI-assisted development as an acceleration of rework: code arrives faster, and so do the defects, the architectural drift, and the review fatigue.
Principles
Intent before implementation
Describe the observable behaviour you need before anyone — human or agent — proposes how to build it. A solution written down too early quietly becomes the requirement.
Specify the negative space
Non-goals, forbidden states and out-of-scope behaviours carry as much information as the happy path. Most agent failures are enthusiasm, not incompetence.
Every requirement carries its evidence
A requirement with no defined way to verify it is a wish. Each statement in the spec names the test, check or demonstration that settles it.
Delegate in bounded slices
Agents perform far better against a task with explicit boundaries, permitted actions and a definition of done than against a broad instruction to “build the feature”.
Keep the spec alive
Reality argues back. When implementation reveals a better answer, the specification is amended and versioned — it does not silently fall out of date while the code moves on.
Humans own the “what” and the “why”
Problem framing, architectural trade-offs, risk appetite and acceptance are human responsibilities. The “how” is increasingly delegable; the judgment is not.
Loop caption
The spec-driven loop. Each arrow is a checkpoint where a human can stop, correct, or accept.
When heading
When it pays off — and when it does not
When yes
- The work touches money, personal data, permissions, or anything with a regulator attached.
- More than one person — or more than one agent — has to arrive at a consistent answer.
- The system already exists and a wrong change is expensive to unwind.
- You expect the same feature to be re-implemented, ported, or audited later.
- The requirement is genuinely ambiguous and the ambiguity is the real work.
When no
- A throwaway prototype whose only purpose is to make a decision cheaper.
- An exploratory spike where you do not yet know what question you are asking.
- A change so small and so reversible that the spec would exceed the diff.
- A domain you understand so well that the acceptance criteria are already unambiguous in one sentence.
Misconceptions
“It is just waterfall with extra steps.”
Waterfall fixes the whole system up front and resists change. A spec in this method is written per bounded slice, is expected to be amended, and is versioned precisely so that change is visible rather than silent.
“The specification has to be exhaustive.”
It has to be decisive, not exhaustive. A good spec settles the questions an implementer would otherwise guess at, and explicitly marks the ones that are safe to leave to judgment.
“It slows the team down.”
It moves the cost. Most of the time saved by fast generation is lost again in review cycles, rework and defect triage. Specification cost is paid once; ambiguity is paid every time someone touches the code.
“The agent can write the spec too.”
An agent can draft one, and that is a reasonable use of it. But a draft it produced and then implements against is a closed loop with no independent statement of correctness in it. A human has to accept the spec for it to mean anything.
Course glossary +
Executable specification
A behaviour description precise enough that an agent can implement from it and a test suite can be derived from it without further guessing.
Non-goal
A behaviour deliberately excluded from scope, written down so that neither a reviewer nor an agent quietly reintroduces it.
Acceptance criterion
A single, observable, binary statement about the system. If two reasonable people can disagree on whether it passed, it is not yet one.
Traceability matrix
A mapping from every critical requirement to the specific evidence — test, check, or demonstration — that settles it.
Task pack
The bounded unit of work handed to an agent: context, constraints, permitted actions, definition of done, and review checkpoints.
Implementation drift
The gap that opens when code evolves and the specification does not. Detected by traceability, prevented by versioned change requests.
Compare the approaches +
Every method is driven by something
The “-driven development” family is usually presented as a list of competing camps. It is more useful to read it as a single question asked repeatedly: which artefact is allowed to decide what gets built? Each method answers differently, and the answers compose more often than they compete.
| Method | What drives the work | Primary artefact | Strongest at | Costs you |
|---|---|---|---|---|
| VIBE — Vibe coding (no method) | An informal prompt and whatever comes back | Working code, no written intent | Throwaway prototypes and personal tools | No definition of correct; silent architectural drift |
| TDD — Test-Driven Development | A failing test written before the code | A unit test suite | Tight feedback, regression safety, design pressure on interfaces | Describes units well and product intent poorly |
| BDD — Behaviour-Driven Development | A shared example of behaviour in business language | Given–When–Then scenarios | A common language across product, QA and engineering | Scenario suites rot quickly without ownership |
| ATDD — Acceptance-Test-Driven Development | An acceptance criterion agreed before work starts | Automated acceptance tests | Customer-visible definition of done | Needs real discipline to stay automated and current |
| DDD — Domain-Driven Design | The domain model and its ubiquitous language | Bounded contexts and a shared model | Complex domains, integration boundaries, long-lived systems | Heavy for small systems; easy to cargo-cult |
| MDD — Model-Driven Development | A formal model that code is generated from | A UML or domain-specific-language model | Regulated, repetitive or multi-target generation | Tooling lock-in and painful round-tripping |
| CDD — Contract-First / API-First | An interface contract agreed before either side is built | An OpenAPI, protobuf or schema definition | Parallel work across teams; verifiable integration | Says nothing about behaviour behind the interface |
| TyDD — Type-Driven Development | The type system and its signatures | Types that make illegal states unrepresentable | Correctness by construction in expressive languages | Bounded by what your type system can actually say |
| DocDD — Documentation-Driven Development | The user-facing document written first | README, changelog or API documentation | Outside-in thinking; catching bad ergonomics early | Documentation drifts the moment attention moves on |
| SDD — Spec-Driven Development | A written specification of behaviour, constraints and non-goals | The specification plus a requirement-to-evidence matrix | Directing AI agents; keeping human judgment on what and why | Specification maintenance; over-specifying wastes effort |
Note
These are layers, not rivals. A mature spec-driven workflow typically states acceptance criteria in BDD-style examples, expresses interfaces as contracts, and verifies the result with tests that a TDD practitioner would recognise. What spec-driven development adds is the part the others predate: an artefact precise enough to hand to a non-human implementer, and a traceable answer to “how do we know it did what we asked?”
Closing heading
Where spec-driven development sits
Closing
- Ahead of TDD, not instead of it. TDD starts once you know what the unit should do; the specification is where that knowledge is decided, argued over and recorded.
- Above the contract. An API contract fixes the shape of an interface. The specification fixes what happens behind it, including what must never happen.
- Beside the domain model. Domain-driven design gives you the language to write a precise specification in. The specification is where that language gets used to settle a concrete behaviour.
- Against vibe coding — but only on work that will outlive the afternoon. The method earns its cost where correctness is contested, expensive or durable.
Teaching perspective +
This course uses a fictional AI teaching persona, not a real instructor.
Name
Arman Farhadi
Role
Specification design & agent-directed delivery
Bio
Arman is the teaching persona for Spec-Driven Development. His course perspective connects clear problem definitions, small implementation steps, and evidence-based verification.
Approach
Start with the behavior you need. Give the agent boundaries. Make the result prove itself.