SDSection 7 →

Section 6 · Lesson 1

Living Specs & Executable Guardrails

Transform specs from static documents into active guardrails — test-driven specs, structured scenarios, a test-first gate, and an objective, auditable definition of done.

"When your team says a feature is done — is that an opinion, or a verifiable fact?

The gap between plan and shipped code

Detailed specs hand off to engineering; weeks later the feature is not quite right. That drift blows budgets, slips timelines, drives rework, frustrates teams, and erodes customer trust when bugs reach production.

Why specs and tests drift apart

Traditionally requirements live in documents while tests live in the codebase — a gap opens almost inevitably. In spec-driven workflow, requirements are written to produce tests. That link ties intent to the reality of the code.

Specs as executable guardrails

Stop treating specs as wishlists. Treat them as guardrails that actively validate themselves — catching drift the moment it happens, not during a frantic late QA cycle.

Test-driven specs

Embed validation in the spec itself. You get an objective, automatable source of truth — a rock-solid definition of done that humans and AI agents can agree on, with far fewer arguments about “done.”

Scenarios — not vague user stories

Precise, structured behavior descriptions that translate directly into automated tests. Robust specs cover three types: the happy path (ideal flow), edge cases (time zones, duplicates, weird inputs), and error cases (graceful, secure failure).

Given · When · Then

Given sets initial system state. When is the action or trigger. Then defines the expected outcome. The template is simple but forces clarity and removes ambiguity — a perfect instruction set for developers and AI agents.

Test first is governance, not preference

In spec-driven development, test-first is risk management policy — not personal style. Tests before implementation catch flawed assumptions when they are cheapest to fix. A test-first gate blocks coding until the safety net is proven.

From examples to properties

Example-based tests ask: does it work for this input? Property-based tests (PBT) ask: is this behavior always true for any valid input? Define an invariant; frameworks generate hundreds or thousands of inputs hunting for counterexamples.

Objective definition of done

Every acceptance criterion maps one-to-one to a scenario and therefore a test. If a requirement exists, it has an automated check. Done is not when code is written — done is when all tests derived from original intent are passing.

Opinion vs verifiable fact

When your team says a feature is done, is that an opinion or a fact? Shifting from opinion to verifiable signal is how you ship more reliable software, faster.

Three scenario types

Happy path

The ideal flow when everything works as designed — baseline behavior you must get right first.

Edge cases

Where systems usually break — time zones, duplicate requests, boundary values, concurrency quirks.

Error cases

Explicit failure behavior — secure, graceful degradation instead of catastrophic breakage.

Given · When · Then

Given

Initial state

Given a signed-in user with an empty cart

When

Action / trigger

When they add a valid SKU

Then

Expected outcome

Then the cart count increases by one and totals update

Test-first gate

Run this checklist before any implementation. Only when every item passes should development begin.

  • Every requirement maps directly to at least one test or scenario
  • Negative paths and error cases are explicitly covered
  • Verification commands are baked into tasks and docs (exact CLI, not “run tests”)
  • Tests fail before implementation starts — the safety net is real, not theater
Clarification Gate (Section 4) →

Example-based

Example-based tests: “Does it work for this specific input I thought of?” — essential, but easy to miss blind spots.

Property-based (PBT)

Property-based tests: “Is this rule always true for any valid input?” — frameworks like Hypothesis (Python) and FastCheck (JavaScript/TypeScript) stress-test invariants you define.

Deep dive: Property-based testing (Section 6 · Lesson 3) →

Requirement traceability template

A living audit trail from requirement ID to scenario, exact verification command, and pull request — transparent and rigorous.

RequirementScenarioVerificationPR
REQ-001Given … When … Then … (happy path)pnpm test --filter checkout#142
REQ-001Given … When duplicate submit … Then idempotent responsepnpm test checkout.edge#142
REQ-002Property: totals never negative for valid cartpnpm test cart.properties#143
Feature verification (Section 3) →

Practice

Check your understanding

A few minutes of recall now saves rereading later.

0 of 3 answered
  1. 1.In a living spec, acceptance criteria are written so they can…

  2. 2.Which is not one of the three scenario types?

  3. 3.Before implementation starts, the derived tests should…