ConstructiCat Logo
CodeBust.
Browse section ▾

Spec-Driven Development.

Also known as — SDD

Write an explicit, authoritative specification first, then drive implementation, tests and generated code from it — keeping the spec as the single source of truth.

##Intent

Make a precise specification the primary artifact of development. Implementation, tests and even AI-generated code are derived from and verified against the spec, rather than the spec being a throwaway document written before the "real" work.

##Problem

Requirements usually live in people’s heads, chat threads or stale documents. Implementation drifts from intent, and when it does there is no authoritative reference to settle what the system should do.

This bites hardest with AI-assisted coding: a vague prompt yields plausible-looking code that may not match what was actually wanted, and there is nothing concrete to check it against.

##Solution

Capture the intended behavior in a clear, versioned specification — scenarios, acceptance criteria and contracts — and treat it as the source of truth. Generate or guide the implementation (often with AI assistance) from the spec, derive conformance tests from the same spec, and verify the implementation against them.

When behavior needs to change, you change the spec first and let the implementation and tests follow. The spec, not the code, is what the team reviews and argues about.

##Structure

  • Specification — intent, scenarios, acceptance criteria and contracts/schemas, kept under version control.
  • Generation / implementation — code produced or guided to satisfy the spec.
  • Conformance tests — checks derived from the spec that the implementation must pass.
  • Feedback loop — discrepancies update the spec, which re-drives code and tests.

##Applicability

  • Use it for AI-assisted development, where a precise spec turns a vague prompt into checkable intent.
  • Use it for contract-first APIs, multi-team coordination and regulated or auditable systems.
  • Avoid heavyweight specs for tiny scripts or exploratory spikes, where they cost more than they return.

##How to Implement

  1. Write the spec: intent, concrete scenarios, acceptance criteria and any contracts or schemas.
  2. Review it with stakeholders — this is where disagreements get resolved.
  3. Derive acceptance / conformance tests from the scenarios.
  4. Implement to satisfy the spec, frequently with AI assistance guided by the spec.
  5. Run the conformance tests; treat failures as either bugs or signals to refine the spec.
  6. Keep the spec authoritative — update it first whenever behavior changes.

##Pros & Cons

Pros
  • A single, reviewable source of truth keeps intent explicit.
  • Pairs naturally with AI code generation, turning prompts into verifiable contracts.
  • Conformance can be checked automatically, reducing drift.
  • Decisions are debated on the spec, before code is written.
Cons
  • Real upfront effort to write and maintain the specification.
  • Specs rot and mislead if they are not kept in sync with reality.
  • Tooling and conventions are still maturing.
  • Over-specifying can be as harmful as under-specifying.
← Previous
Test-Driven Development