Spec-driven development treats a structured specification—not the codebase—as the system of record. This post maps who does what when you work that way: from turning product intent into an agent-readable spec, through API contracts and UI rules, to validation that implementation still matches what you wrote down.

Table of contents

• Overview
• When this helps (and when it does not)
• What usually lives in the spec
• 1. Product owner / product manager
• 2. UI/UX designer
• 3. Backend engineer / architect
• 4. Frontend engineer
• 5. Quality assurance / tester
• 6. Engineering lead / tech lead
• Tooling and automation
• Common pitfalls
• How this relates to BDD and TDD
• Summary of workflow
• Key difference from traditional development

Overview

Spec-driven development (SDD) is a way of working where a structured, often machine-readable document—the spec—is the single source of truth, not the running code. Requirements are pinned down before or alongside implementation; code is expected to follow the spec, and when reality diverges you fix the spec first (or consciously change it), then align the code.

That discipline matters most when humans and coding agents share the same brief: ambiguity in the spec becomes wrong behavior in production. The sections below are a role-by-role split of who typically authors which parts and who checks them.

When this helps (and when it does not)

SDD tends to pay off when:

• Multiple teams (or people and agents) touch the same feature and need a shared contract.
• APIs and data shapes are stable enough that writing them down early saves rework.
• You need audit-friendly traces from “what we agreed” to “what shipped.”

It is a weaker fit when:

• The problem is still pure discovery (spikes, prototypes where throwaway code is the point).
• The spec would duplicate a product that changes daily without anyone updating the doc.
• “The spec” becomes so large that nobody reads it—then you have ceremony without clarity.

What usually lives in the spec

A practical spec often mixes narrative and artifacts, for example:

• Intent: User journeys, goals, non-goals, and explicit out-of-scope items.
• Behavior: Scenarios (Given/When/Then or similar), including errors and edge cases.
• Interfaces: API descriptions (for example OpenAPI), event schemas, or integration points.
• Data: Entities, validation rules, invariants, and migration or backward-compatibility notes.
• Quality bar: Performance, security, accessibility, and observability expectations.
• Acceptance: How you know the work is done (automated checks, manual sign-off, or both).

The exact shape (one repo SPEC.md, RFCs, ADRs, or a folder of feature specs) matters less than versioning, ownership, and a habit of updating the spec when decisions change.

1. Product owner / product manager

The PO or PM usually owns the specify slice: turning business needs into a precise document that developers or agents can follow without inventing requirements.

• Defining behavior: User stories or scenarios in a structured form (for example Given/When/Then), not only high-level wishes.
• Acceptance criteria: Success conditions plus edge cases, failure modes, and what “done” excludes.
• Review before build: Acting as human-in-the-loop so implementation starts from an approved baseline, not a moving chat thread.
• Living document: When priorities shift, the spec updates; tickets alone are not enough if the spec is supposed to be authoritative.

2. UI/UX designer

Designers contribute enforceable intent, not only static mocks.

• Specs over handoffs: Alongside Figma (or similar), design tokens—spacing, color, type scales—are written into the spec so generated or hand-written UI can be checked against them.
• Flows and states: Happy path, empty states, loading, errors, and permissions live in the spec so implementation is not guessed from a single frame.
• Layout rules: Breakpoints, component hierarchy, and constraints (what must not change without a spec change) are explicit.

3. Backend engineer / architect

Backend work centers on contracts and invariants that other roles depend on.

• API-first: OpenAPI (or equivalent) in the spec enables parallel frontend work and gives QA a contract to test against.
• Data modeling: Schemas, validation rules, and consistency guarantees are documented where the spec lives, not only in migrations.
• Architecture boundaries: Stack choices, security rules (authn/z, PII handling), and integration assumptions are stated so agents and juniors do not override them silently.

4. Frontend engineer

Frontend engineers implement against the agreed structure and contracts.

• Reading the spec: Component boundaries, interaction rules, and token usage come from the spec; agents can scaffold from the same file if your team works that way.
• Styling: Tokens and layout rules from the spec reduce one-off CSS drift.
• Data alignment: UI maps to the API and event shapes defined in the spec, so integration surprises surface as spec violations, not mystery bugs.

5. Quality assurance / tester

QA shifts toward proving the implementation matches the spec.

• Executable specs: Where possible, behavior in the spec is reflected in automated checks (from BDD-style suites to tools that map natural language steps to tests—teams differ widely here).
• Adversarial verification: Deliberate attempts to break documented behavior, including negative paths omitted from happy-path demos.
• Contract testing: Services and consumers are checked against the published API spec so drift is caught before release.

6. Engineering lead / tech lead

Leads enforce process around the spec, not only code review taste.

• Definition of ready: No significant build starts without a spec baseline and named owners for API, UX, and acceptance.
• Traceability: Changes that skip the spec (or leave it stale) get flagged; the spec and PR should tell the same story.
• Sizing and risk: Ambiguous specs are sent back for clarification rather than absorbed as hidden scope in implementation.

Tooling and automation

Tooling varies by stack, but common patterns include:

• Contract artifacts: OpenAPI/AsyncAPI/JSON Schema checked into the repo and reviewed like code.
• CI gates: Breaking API changes fail the build; contract tests run on PRs.
• Linting and formatting: Specs in structured formats can be validated automatically; markdown specs can still use checklists and required sections.
• Agent workflows: Plain language plus clear section headings and stable identifiers (feature IDs, scenario names) make specs easier for both humans and tools to parse.

Common pitfalls

• Stale spec: Code and production behavior move; the document does not. Treat outdated specs as defects.
• Over-specification: Documenting every pixel for a throwaway experiment slows you down; match depth to risk and lifespan.
• Spec as wishlist: Vague phrases (“fast,” “secure,” “intuitive”) without measurable criteria do not reduce ambiguity.
• Two sources of truth: If Jira and the repo spec disagree, teams will guess. Pick a primary artifact and link the other to it.

How this relates to BDD and TDD

• BDD: Scenario-style specs overlap heavily with SDD; the spec often is or feeds the behavioral examples you automate.
• TDD: You can still write tests first; in SDD those tests should trace to documented behavior. The spec answers what must hold; tests prove the code obeys it.

SDD does not replace tests—it tells everyone, including agents, what the tests (and code) are supposed to enforce.

Summary of workflow

1. Specify: PO and design define what to build in a versioned spec (often markdown plus embedded schemas).
2. Plan: Backend and architecture define how at the contract and data layer; interfaces land in the spec.
3. Implement: Engineers and/or agents build from the spec. When coding turns up gaps, contradictions, or new edge cases, those findings go into the spec first (or you consciously change the product decision there), then the code follows.
4. Validate: QA and automation show that behavior matches the spec and contracts.

Key difference from traditional development

In many traditional setups, the running code and tribal knowledge act as the source of truth. In SDD, the spec is the source of truth: if behavior is wrong, you decide whether the spec or the code is wrong, update the spec when the product decision changes, then align implementation. That loop keeps agents, new hires, and future you from guessing what “correct” was supposed to mean.