SDD Foundations

Learning objectives

By the end of this module, you will be able to:

1. Explain why AI agents move the bottleneck upstream, and what it means for a spec to be executable rather than disposable scaffolding.
2. Define a “spec” and tell it apart from a PRD, a design doc, or a detailed prompt.
3. Separate the two persistence questions — how long a spec matters, and how the artifact set changes — and name the main risk of each model.
4. Walk the full and short Spec Kit workflow, from constitution to converge, and say what each step produces.
5. Say where a person decides at each human gate, and what the implement–converge loop and “Converged” mean.
6. Place the workflow in SPECTRA’s seven agentic SDLC phases.
7. Recognize when SDD is overkill, and articulate its main critiques honestly enough to push back when adoption is oversold.

1.Why this is happening now

For decades, code has been the source of truth in software development. We write requirements docs and they drift. We draw architecture diagrams and they rot. We write tests, often after the fact. The code — whatever it actually does — becomes the de facto truth of the system, and “what should this function do?” gets answered with “read the code.”

That stayed manageable as long as humans were the bottleneck on writing code. AI coding agents have changed that. When an agent can produce a working endpoint in 30 seconds, the bottleneck shifts upstream. The new constraint is: how clearly can you state what you actually want?

Spec-driven development is the answer to that question. Rather than typing increasingly elaborate prompts into a chat window, you write a structured specification first, and the agent uses it as the authoritative description of what to build.

Spec Kit, the open-source toolkit this course is built on, frames it as reversing an old relationship. A spec used to be scaffolding, taken down once the “real” coding began. In SDD the spec stays up: it is the input the agent generates from and the yardstick the result is measured against. Spec Kit’s word for that is executable.

The simplest way to put the inversion (from Piskala’s 2026 paper):

In spec-driven development, code is the implementation detail of the specification — not the other way around.

That’s the whole idea. Everything below is detail.

Three kinds of work SDD is for

Spec Kit names three development phases the method serves. You’ll do two of them in this course.

• Greenfield (zero to one). From high-level requirements to a spec, a plan, and something new. Module 3’s lab.
• Creative exploration. Several implementations of one spec — different stacks, architectures, or UX patterns — compared side by side. With the intent held in the spec, building twice is affordable.
• Brownfield (iterative enhancement). Adding features to an existing system, or modernizing a legacy one. Module 4’s lab. Each change brings its own small spec, and the areas that change most often gradually build up spec coverage.

2.What is a spec, exactly?

You’re going to hear “spec” used loosely in tutorials, vendor blog posts, and social media threads. Some people use it to mean “a slightly longer prompt.” Others mean “a regenerated copy of the codebase in markdown form.” Neither is what we mean.

For this course, a spec has three properties:

1. Structured. It follows a known format, not just prose. Sections for user scenarios, requirements, success criteria, scope.
2. Behavior-oriented. It describes what should happen and why, not how it’s implemented.
3. Executable. It is consumed by tooling — AI agents, consistency checks, CI gates, contract tests — not just read by humans.

That third property is what separates a spec from a PRD or a design doc:

That’s the bar: when the code and the spec disagree, something notices — a converge pass, a failing test, a CI gate — and a person resolves it before merging.

What a spec is not

• It is not a code-shaped artifact. If your spec reads like pseudo-code, you’ve gone too far down toward “how” and lost the abstraction. Stack and architecture belong in the plan.
• It is not exhaustive. You don’t spec everything. You spec what’s needed to remove ambiguity for the current piece of work.
• It is not generated and forgotten. If you generate a spec, never review it, and let an agent implement against it, you have a vibe-coding loop with extra steps.

3.How long a spec lives — and how it changes

Not all SDD adoption looks the same, and most of the confusion online comes from people answering different questions without realizing it. There are two, and they are independent:

1. How long does the spec matter? Only until the code exists, or for the life of the system?
2. When requirements change, what happens to the artifacts you already have? Do you edit them, or leave them as history and start new ones?

3.1 How long the spec matters

Spec-first is where almost every team should start. Spec-anchored is the sweet spot for most production systems: BDD with Cucumber and contract testing with Pact or Specmatic both predate the “SDD” label, and both are fundamentally spec-anchored. Spec-as-source is real in narrow domains — automotive control software generated from Simulink models for ISO 26262, for example — and tools like Tessl are exploring it more broadly, but it remains experimental for business software. If someone tries to sell you spec-as-source for your CRUD app, push back.

3.2 How the artifact set changes

The second question is about spec.md, plan.md, and tasks.md once they exist and a requirement moves. Spec Kit names three models:

3.3 A team convention, written in the constitution

Spec Kit doesn’t answer either question for you, and there is no CLI setting for it. The choice is a team convention: make it explicitly and record it in the constitution (.specify/memory/constitution.md), so every contributor — and every agent — reads the same rule. Two questions get you most of the way: are finished feature directories history or editable work areas? And is spec.md the single source of truth, or may plan.md and tasks.md become co-equal sources?

Where our team starts: spec-first for greenfield work, one small spec per change for brownfield work, spec-anchored where contracts are already stable (APIs you publish, modules other teams depend on). For the second question there is no house default — choose deliberately, per project.

4.The spec-driven workflow

Every SDD tool you’ll encounter — GitHub Spec Kit, Kiro, OpenSpec, Tessl — shares one spine: specify what, plan how, break it into tasks, implement. Spec Kit adds a constitution up front, three optional quality gates, and a verification step at the end. We use Spec Kit’s vocabulary because the labs run on SPECTRA, which is built on it: the commands and artifacts are Spec Kit’s, and SPECTRA installs them and layers its own agents around them.

4.1 Once per project: the constitution

/speckit-constitution writes .specify/memory/constitution.md: the principles — coding standards, testing rules, architectural constraints — that every later step is checked against. Run it before the first feature, and again whenever a principle changes. SPECTRA calls the agent behind it Guardrails: standards encoded once instead of repeated in every prompt. Module 2 looks at what belongs in it.

4.2 The full path, step by step

Keeping specify and plan apart is the habit that matters most, and the one most engineers struggle with at first. Compare two prompts for the course’s to-do app:

/speckit-specify Let people filter the to-do list to show all, active, or completed items. The chosen filter should still be selected after a page reload.

/speckit-plan Next.js App Router, React, and TypeScript, as the app already uses. Keep the filter state in app/page.tsx next to the list, and persist it through lib/storage.ts.

The first says what a user gets. The second says how it will be built. When a specify prompt names a framework, a function, or a database column, it’s in the wrong step.

4.3 The short path

For a small feature, drop the three optional gates: once the constitution exists, run specify → plan → tasks → implement → converge. Only /speckit-specify is strictly required before /speckit-plan. SPECTRA’s roster lists clarify, checklist, and analyze as add-on agents you switch on as needed, next to the core agents that run the loop end to end. Switch them on whenever there is real ambiguity or the feature is headed for production — skipping them on a feature full of open questions just moves the questions into code review.

4.4 Implement and converge: the closing loop

/speckit-implement works through tasks.md phase by phase, in dependency order. Before it starts, it counts the items in every checklist; if any are unchecked, it asks whether to continue. It never ticks a box itself. On a large feature, scope each run and verify the result before starting the next:

/speckit-implement only execute tasks T001-T010, then stop and report progress

When implement finishes, run /speckit-converge. It compares the codebase against the spec, plan, and tasks, summarizes its findings by severity, and ends in one of two ways:

• Converged. Nothing the artifacts ask for is left unbuilt, and tasks.md is left exactly as it was. Move on to review and the pull request.
• Tasks appended. It found gaps and added them as new tasks under a Convergence section of tasks.md. Run /speckit-implement to build them, then converge again. Each pass should find less; repeat until it reports Converged.

Converge is append-only: it leaves your code alone, never removing a line, and appending tasks is the only write it can make. So “Converged” is a statement about coverage, not a code review — the build matches what was written down. Whether that is right is still your call.

4.5 Where you stand at each gate

SPECTRA’s short version is agents draft, people decide — agentic, not autonomous. Four gates are easy to get wrong:

• Clarify — you answer. The agent finds the ambiguity and asks; you decide. If you don’t know an answer yet, chase it down before planning rather than guessing.
• Checklist — you tick. A custom checklist from /speckit-checklist belongs to the reviewer: the command never marks its own items, and an item gets [x] only when a person is satisfied. The agent can help evaluate when asked, but never silently approves. A tick means “this requirement is well written,” not “this code is done.” The built-in checklists/requirements.md is different: specify and clarify tick and untick it themselves, so its ticks are the agent’s own claim, not a sign-off.
• Analyze — you fix at the source. Analyze only reports. A requirement problem goes back to specify or clarify, a design problem to plan, a task-list problem to a fresh run of tasks; then re-run analyze until it’s clean. Hand-patching tasks.md to silence what is really a spec gap just hides the gap.
• Implement — you review each stage. Read the code and the updated artifacts together. If the output doesn’t match the spec, fix whichever was wrong — code or spec — and keep the spec authoritative.

Because each step produces an artifact that constrains the next, each is also a review checkpoint. By the time you’re looking at a pull request, divergence has had several chances to be caught. When a team complains that “AI-generated code is hard to review,” it’s usually because they skipped straight to the code and tried to review only the output.

4.6 The workflow inside SPECTRA’s agentic SDLC

SPECTRA describes the whole lifecycle as an agentic SDLC in seven phases, each with a human gate. The Spec Kit workflow covers the first five. Every phase reads and writes the same durable artifacts — constitution, specs, plans, tasks, decision records — so no phase starts cold.

Checklist runs after plan in the command sequence, but it tests the requirements, not the design — which is why it sits in Plan.

Two paths sit outside this sequence. Idea assessment (Module 5) happens before any of it: it decides whether Plan should start at all. Bug fixing (Module 6) is a separate path and doesn’t need SDD first — you can run it on a codebase that has no specs at all. Both are Spec Kit workflows, added to a project with specify extension add.

5.How SDD relates to things you already know

TDD

A unit test is a micro-spec. You write the test first, declaring what the function should do; then you write the function. SDD extends the same “specify before you build” thinking up to feature, system, and architectural scope.

Use both. TDD at the unit level, SDD at the feature/system level. They don’t compete.

BDD

Behavior-driven development is the most direct ancestor of modern SDD. Gherkin scenarios — Given / When / Then — are literally executable specs. Cucumber and SpecFlow have been turning them into automated tests for over a decade.

What changed: AI agents can now generate code from those scenarios, not just verify against them. This is why people like Bryan Finster (who has been doing BDD for years) call SDD “BDD with branding.” He’s not entirely wrong.

If your team already runs BDD, SDD is the smallest possible step from where you are. You’re already most of the way there.

Contract testing and contract-driven development

Pact and Specmatic have enforced agreements between services for years. Spec Kit folds the idea into SDD as contract-driven development: when a component exposes an interface that something else consumes — an API, a library, a CLI whose output gets parsed — agree on its observable obligations (inputs, outputs, errors, guarantees such as retry safety) before building either side. One side owns the contract, the agreement is settled during planning, and each side then builds and tests against it, whatever your architecture or repository layout.

PRDs and design docs

These are advisory. Humans read them and write code that hopefully matches. Drift is normal and expected; nobody is alarmed when a 6-month-old design doc no longer matches the code, because nothing in the system enforces alignment.

SDD specs are enforced: the agent builds from them, and a mismatch between spec and code is flagged and has to be resolved.

This is the cultural shift the team has to internalize: documents that nobody enforces become decoration. Documents that the workflow enforces become contracts.

Agile / Scrum

User stories with acceptance criteria are specs. The Definition of Done is a form of spec. You’re already specifying things. SDD asks you to do that with more discipline and to make the specs authoritative rather than advisory.

You don’t need to change your sprint structure to adopt SDD. You change what counts as “done” for a story and what artifacts get versioned.

6.When not to use SDD

There are tasks where spec ceremony costs more than it saves. The honest list, drawn from Augment’s “skip the spec” criteria:

The trigger heuristic that’s worth memorizing:

If you’d be annoyed to have the agent interpret requirements differently than you meant, write the spec. If you could fix the output in a quick follow-up prompt, skip it.

This is calibrated by stakes, not by intrinsic complexity. A two-line auth token check might warrant a spec because misinterpretation has security consequences. A 200-line refactor of a private function might not, because if the AI misreads, you’ll catch it on diff review.

Skipping the spec doesn’t have to mean skipping structure. A defect with a clear symptom has its own lighter path — Spec Kit’s bug workflow, which you’ll run in Module 6 — and an idea nobody has vetted yet is better assessed (Module 5) than specified.

7.The honest case against (and why we’re doing it anyway)

Spec-driven development has serious critics, and you should hear them before adopting any practice. This is the part most vendor blog posts skip.

Birgitta Böckeler (Thoughtworks): “Verschlimmbesserung”

Böckeler used Spec Kit, Kiro, and Tessl on real problems and found that current SDD tools generate too many files for the size of the problem they solve. Applied to a small bug fix, Spec Kit produced 4 user stories and 16 acceptance criteria when one prompt would have been better. She uses the German word Verschlimmbesserung — “an improvement that makes things worse” — for SDD setups that generate more markdown than code.

Her concrete warning: reviewing markdown can be harder than reviewing code. If your specs are repetitive, contain code-like detail, or duplicate what the code already says, you’ve made your job harder, not easier.

Take this seriously. Spec Kit now offers a short path for small features and a separate, lighter workflow for bug fixes, but the warning still applies to anything you push through the full loop. We’ll cover countermeasures in Module 8 (Best Practices & Pitfalls).

Bryan Finster: “BDD with branding”

Finster’s argument is that the core insight of SDD — write specs first, derive code from them — has been agile/BDD wisdom for two decades. Calling it a paradigm shift in 2026 is marketing.

He’s right that the insight isn’t new. What’s new is:

1. AI agents are now competent consumers of specs, not just humans.
2. CI/CD has matured to the point where spec enforcement is routine, not exotic.
3. Tooling for spec authoring and validation is finally good enough to be worth adopting.

Together, those three changes make spec-first practice more powerful and more enforceable than ever before. So the practice is more valuable now than it used to be, even if the idea has been around for years.

The honest position: SDD isn’t revolutionary, but it’s currently the most practical way to keep AI-generated code aligned with intent in a production codebase.

Why we’re adopting it anyway

Three reasons, in order of importance:

1. It addresses a real problem. When AI agents generate code, the gap between “what we wanted” and “what we got” widens unless something keeps both ends explicit. Specs are that something.
2. It scales review better than PR-time inspection. The Agoda study (10,000+ devs, March 2026) found that high-AI-adoption teams completed 21% more tasks but PR review time grew 91%. Pushing validation upstream into specs is one of the few ways to stop that bottleneck from breaking the team.
3. It improves cross-functional collaboration. Done well, specs become the shared interface between PM, architecture, engineering, and QA. Done badly, they’re just more documentation. Modules 9 and 10 are about making sure we land on “done well.”

8.The mental shift to make

Engineers tend to enter SDD thinking it’s a tooling change: install SPECTRA, learn nine slash commands, done. That’s the version that produces Verschlimmbesserung.

The mental shift that actually unlocks the value:

• Before: Code is the source of truth. Documents describe code.
• After: Specifications are the source of truth. Code implements specs.

In the “before” view, drift is inevitable and you accept it. In the “after” view, drift is a defect and you fix it.

You don’t need to fully internalize this on day one. You’ll get there by doing the labs. But notice when you’re slipping back into “the code is the truth, the spec is documentation” thinking — that’s the failure mode that turns SDD into bureaucracy.

Knowledge check

Spend 10–15 minutes on these. Click an answer to see whether you got it right and why.

What’s next

In Module 2 you’ll look inside a good spec: the six-element framework for writing specs that don’t bloat or drift, and how the constitution keeps cross-cutting rules out of individual specs. You’ll finish with a short writing exercise — rewriting a deliberately bad spec into a good one.

After that, Module 3 moves into the first hands-on lab: installing SPECTRA and running the workflow on a small greenfield feature.