Spec-Driven Development: Build the Intent First, Then the Code

#

TL;DR: In the AI era, implementation is fast. Alignment is the bottleneck. Spec-Driven Development (SDD) makes a single, living specification the source of truth. Plans, tasks, tests, and code serve the spec but not the other way around.

If you’ve ever merged code that worked but didn’t solve the right problem you already know why SDD matters.

The quiet failure mode engineers recognize

#

You’ve seen this play out:

• Tickets describe what to do but not what “done” means.
• API shapes drift between services because “the doc” wasn’t updated.
• Reviews debate taste instead of intent.
• AI tools ship code faster but sometimes the wrong code faster.

Nothing catastrophic, just accumulated friction. The fix isn’t more code; it’s a better contract for what the code should express.

What is Spec-Driven Development?

#

SDD is a straightforward shift:

1. Specify the intent (what & why, plus success criteria).
2. Plan the implementation (how, given constraints & stack).
3. Task it (small, verifiable work items).
4. Implement & verify (change sets that map back to the spec).

Move to the next phase only when the current one is validated. Treat the spec like code: versioned, reviewed, and kept current.

Four phases at a glance

#

┌──────────┐   ┌──────┐   ┌─────┐   ┌──────────────────────┐
│ Specify  │ → │ Plan │ → │ Task│ → │ Implement & Verify   │
└──────────┘   └──────┘   └─────┘   └──────────────────────┘

Why this works with AI

#

Large language models are excellent at pattern completion, not mind reading. Clear specs remove guesswork:

• Better prompts → better scaffolding → fewer rewrites.
• Consistent contracts → fewer “helpful” but incorrect assumptions.
• Repeatable structure → faster onboarding for both humans and agents.

The six lightweight specs that de-risk delivery

#

Keep these as first-class artifacts in your repo:

1. System Overview — scope, constraints, high-level architecture, non-functionals.
2. API Contract(s) — inputs/outputs, errors, pagination, auth.
3. Data Model — entities, invariants, indexes, retention rules.
4. UI Design — flows, states, accessibility criteria, component boundaries.
5. Business Logic — scenarios, rules, edge cases, measurable success.
6. Infrastructure — environments, deploy, observability, security, SLAs.

👉 Rule of thumb: Each spec should be skimmable in 5–10 minutes and testable. Use checklists, tables, and examples—not essays.

From vibes to verifiability: two concrete examples

#

1) Session timeout in a web app

#

Without SDD:

• Designers assume sessions last 15 minutes.
• Backend engineers implement 30 minutes.
• Product expects “Remember Me” to override timeout.
• QA isn’t sure what “inactive” means—no clicks? no network calls?

With SDD:

• Spec: “Default session expires after 20 minutes of no user activity (clicks, keypresses, API calls). If ‘Remember Me’ is checked, extend to 7 days.”
• Plan: “Backend tracks last activity timestamp; frontend sends keep-alive every 5 minutes; logout endpoint clears token.”
• Tasks: Token expiry logic, keep-alive pings, UI update, e2e tests.

The ambiguity is resolved before code is written. Engineers, designers, and QA share the same contract, and everyone knows what “inactive” means.

2) API rate limiting

#

Without SDD:

• Backend sets a hard limit of 100 requests/minute.
• Frontend team thinks it’s 1000/day.
• Product assumes premium users get higher limits, but nobody wrote it down.
• QA can’t test reliably because the “limit” depends on who you ask.

With SDD:

• Spec: “Free users: 100 requests per minute. Premium users: 1000 requests per minute. Exceeding the limit returns HTTP 429 with a Retry-After header.”
• Plan: “Use Redis-based sliding window; per-plan config; log events.”
• Tasks: Middleware, error codes, docs with examples, load tests.

Now everyone knows what the limit is, how it behaves, and how to test it. No more Slack arguments or “but I thought…” moments.

“Isn’t this just more documentation?”

#

Two differences:

1. Structure over prose. Sections are short and testable: contracts, rules, acceptance checks.
2. Kept current by policy. Update the spec before code. PRs reference sections. CI can even block merges if [NEEDS CLARIFICATION] markers remain.

Minimal guardrails that actually help

#

• Spec-first rule: No feature branch without a specs/features/<name>/ folder.
• Clarification markers: Use [NEEDS CLARIFICATION: …] during drafting; must be zero before “Plan” starts.
• Reference discipline: Every PR links the exact spec lines it implements.
• Review posture: Ask “does this match the spec?” before “is this idiomatic?”.

How SDD changes the week for engineers

#

• Planning is concrete. You’re aligning on intent and success criteria, not vibes.
• Reviews are faster. Less back-and-forth on interpretation, more energy on quality.
• AI is more useful. Models generate closer to target on the first pass.
• Onboarding is smoother. New folks read six small specs instead of walking in code paths.

Getting started next sprint (small, real, now)

#

Pick a single feature and create four tiny files under specs/features/<feature>/:

• api-contract.md — inputs/outputs, errors, limits (1–2 pages).
• data-model.md — entities, invariants, indexes (1 page).
• ui-design.md — flow diagram, empty/error states, accessibility checks (1 page).
• business-logic.md — scenarios, rules, edge cases, success criteria (1–2 pages).

Add two org-level docs (often one-time):

• specs/system-overview.md — purpose, constraints, cross-cutting concerns.
• specs/infrastructure.md — environments, deploy, monitoring, rollback policy.

Wire your workflow:

• Policy: Update spec → then code.
• PR template: “Spec sections implemented:” (links).
• Retro: Track “spec mismatch” incidents and fix the spec, not the rumor mill.

Common pitfalls & how to dodge them

#

• Over-specifying. Aim for clarity, not completeness.
• Spec drift. Make “spec diff” part of planning and review.
• Essay writing. Prefer tables, checklists, examples.
• Skipping edge cases. Force yourself to list at least five—it’s where most rework hides.

A quick worksheet (engineer’s version)

#

Before touching code, confirm you have:

• Inputs, outputs, and error schema (with examples).
• Invariants & acceptance checks (“how we know it works”).
• 3–5 edge cases with expected behavior.
• Operational notes: logs, metrics, alerts, rollout/rollback.
• Ownership: who approves spec changes?

If any box is blank, you’re optimizing for speed over correctness.

In the end, SDD isn’t about writing more docs—it’s about making intent executable. Specs become the language both humans and AI can follow without guessing.

Further Reading & Credits

#

• Spec Kit — Den Delimarsky & team
• Mastering AI Agents: From Vibe Coding to Specification-First AI Engineering — Mario Cartsburg

Question for you: If you applied SDD to exactly one feature next sprint, which would save your team the most rework—and what’s the smallest spec you need to make it unambiguous?