Spec-Driven Development: How Executable Specs Make AI Coding Production-Ready

Introduction: The Problem with Vibe Coding

Imagine asking an AI agent to implement an "order export" feature. It quickly produces working code — frontend button, backend API, file download — but then you discover it outputs user phone numbers in plain text, exports hundreds of thousands of rows, and places core logic in the frontend. You spend an afternoon cleaning up. This isn't the AI's fault; it received a "bad requirement."

Most AI coding rework happens before the first line of code. Requirements only state direction; interfaces lack contracts; database boundaries are unconfirmed; acceptance criteria stop at "looks usable." The agent follows its own inferences, and its guesses are wrong more often than expected.

Spec-Driven Development (SDD) Overview

SDD brings traditional software engineering specification practices into the AI era. The logic is simple: define specifications clearly before AI touches code, so the model generates implementations around fixed goals, constraints, and acceptance criteria instead of guessing.

SDD aims for "executable documentation." Functional goals, inputs/outputs, architectural boundaries, data models, interface contracts, exception handling, and verification methods become hard constraints that the agent can read, execute, and use to produce delivery evidence.

Core Principle: Specification precedes code; code undergoes specification validation. The stronger the AI generation capability, the more we must define boundaries upfront.

Spec-Driven Development Flow
Specification first, generation controlled, verification closed-loop
Requirements Analysis → Business Goals & Scope
Specification Writing → Contracts & Constraints
Specification Review → Product & Engineering Confirmation
Context Injection → Spec + Rules + Code
AI Generation → Minimum Safe Slice
Automated Verification → Tests / Build / Static Analysis
Human Review → Gaps & Risks
Merge → Code & Spec Sync
On deviation found in verification or review, return to spec revision, then next implementation cycle

Flow overview: Requirements Analysis → Write Contractual Spec → Multi-party Review → Inject Spec+Rules+Code into AI → AI Generates per Constraints → Automated Verification → Human Review → Merge with Code-Spec Sync

Throwing a one-liner at AI is "luck-based" development; spec-based development puts AI back on an "engineering" track. The spec becomes the shared basis for generation, testing, review, and merge, shifting discussion from "model capability" to "contract quality."

1. The Specification Itself Is an Engineered Prompt

In SDD, prompt engineering is no longer "please implement feature X" but a structured specification. A high-quality prompt essentially contains goals, constraints, inputs/outputs, forbidden paths, acceptance criteria, and verification methods — identical to a good spec.

Writing requirements in natural language produces a "bad prompt" — vague, open, ambiguous. Structured specifications give the AI a top-tier, deterministic prompt. The model shifts from improvisation to constrained implementation: fewer guessed fields, fewer unfamiliar dependencies, fewer architectural bypasses, fewer exception paths left for manual rescue.

Specifications also improve reproducibility. Same spec, same project rules, same verification commands yield similar plans and implementation paths across different agents or runs. This depends on spec granularity and model capability, but provides a baseline for reproducibility and a benchmark for review. Review shifts from "did the model have inspiration?" to "does the implementation satisfy the contract?"

Concrete Example: Order Export Specification

Spec Fragment Example: Order Export

Feature
Order management page supports exporting currently filtered results by creation time.

Business Goal
Operations staff need quick access to order details for daily reconciliation.
Current goal: reduce manual copying and ad-hoc backend queries.

Input
start_time: ISO 8601 string, required.
end_time: ISO 8601 string, required.
status: paid / unpaid / refunded, optional.
Single time range max 31 days.

Output
Return xlsx file.
Fields: order number, creation time, payment status, order amount, recipient, masked phone number.
Empty result exports header only.

Architecture Constraints
Export logic in order application service.
Controller handles only parameter validation and response transformation.
Must not assemble export data in frontend.

Database Constraints
Reuse orders table and existing order query conditions.
Confirm created_at + status composite index covers export query.
No new order snapshot table this iteration.

API Contract
GET /api/admin/orders/export
Permission: order:export.
Error codes:
403 No export permission.
422 Time range exceeds 31 days.
500 File generation failed.

Acceptance
User with order:export permission can export orders within 31 days.
User without permission sees no export entry; direct API request returns 403.
Empty result file contains only header.
Exceeding time range returns 422 without file generation.

Edge Cases
Export API timeout → frontend shows retry prompt.
User clicks export button repeatedly → frontend disables button until request ends.
Order amount formatted per backend standard, avoiding frontend recalculation.

With this spec, AI-generated code struggles to deviate — every field constrained, every path expected, every boundary handled.

2. Specification-First Solves Inference Runaway

In the opening scenario, why did AI output plain phone numbers? Because the requirement didn't mandate masking; it "inferred" the simplest approach. Human engineers ask clarifying questions; agents default to a plausible solution and execute — more defaults mean higher downstream fix costs.

SDD surfaces these "default solutions" upfront as hard constraints. Clear business goals prevent feature drift; explicit inputs/outputs prevent field and boundary drift; interface and database constraints keep implementation aligned with existing systems.

Essentially, SDD step one converts "what humans know" into documented hard constraints. AI handles execution, implementation details, and verification evidence generation; humans define goals, boundaries, and trade-offs.

Four Questions to Resolve Before SDD Business Problem: Whose problem, what problem, how to measure completion. Scope Boundaries: What's included, deferred, explicitly excluded. System Constraints: Which architecture, permission, data, and interface rules to follow. Verification Methods: Which tests, builds, logs, or manual checks prove completion.

3. Structured Specifications Must Cover Seven Elements

Specification value comes from structure. Natural language paragraphs suit background explanation, but only structured fields truly constrain AI execution space. Every feature or module entering AI implementation must cover at least seven elements:

Feature Description: Clear business goal, stating what to do without prescribing implementation details. Role: lets model make trade-offs around the goal.

Input/Output Definition: Data formats, type constraints, required fields, ranges, null handling, boundary conditions. Role: reduces field guessing and type drift.

Architecture Constraints: Layering rules, dependency direction, communication patterns, module boundaries, prohibited actions. Role: prevents implementation from bypassing system structure.

Database Constraints: Entities, relationships, index strategy, migration rules, compatibility and rollback requirements. Role: controls data layer risk.

Interface Contract: API endpoints, request/response formats, error codes, permissions, idempotency rules. Role: lets frontend, backend, and testing share one contract.

Acceptance Criteria: Testable completion conditions covering user-visible results and internal system states. Role: turns definition of done into a verification checklist.

Edge Cases: Exception inputs, concurrency scenarios, failure retry, degradation strategies, security limits. Role: approaches real production paths.

These seven elements need not be one large document. Small features fit in a one-page spec; large modules split into multiple spec files. Key is each element influences AI implementation decisions.

4. Specification Review Matters More Than Prompt Polishing

Many teams invest in prompt tricks but neglect whether the spec itself holds. Prompts improve expression but cannot make business decisions — where boundaries lie, who owns data risk, how acceptance is defined — these determine quality.

Since the spec is the AI's execution contract, its review is more critical than prompt polishing. Product, engineering, testing, and security roles discuss the same spec: goal clarity, interface stability, database migratability, testability of acceptance criteria, completeness of exception paths.

After review, the spec graduates from "requirements draft" to "execution contract." Subsequent agent plans, code, tests, and self-checks must all deliver evidence against this contract.

Specification Review Must Yield Clear Conclusions Pass: Spec enters context injection and implementation planning. Supplement: Missing fields, exceptions, permissions, data, or acceptance details; revise and re-review. Split: Scope too large or risk too high; split into multiple verifiable specs.

5. Context Injection Must Deliver a Complete Execution Package

After spec review, context injection begins. Context isn't dumping all materials into the model; it's packaging execution constraints clearly. A stable context package typically contains four layers:

Feature Spec: Functional goals, inputs/outputs, interface contracts, acceptance criteria.

Project Rules: e.g., AGENTS.md, CLAUDE.md, Cursor Rules, or repo-level Copilot instructions — architecture layering, coding standards, permission boundaries, dependency constraints.

Code Context: Relevant modules, similar features, database migrations, existing tests.

Verification Plan: Automated tests, build checks, manual review paths, and completion evidence.

This step determines the agent's working mode. Given only requirements, the model finds its own path; given spec, project rules, and verification plan, the model plans first, implements second, delivers evidence last.

6. Automated Verification Closes the Loop

After AI generates code, SDD doesn't stop at "implementation done." Automated verification maps directly to spec acceptance criteria. Functional logic → unit tests; interface contracts → integration tests; database migrations → migration checks; critical user paths → end-to-end or manual checks.

When verification fails, first classify the cause: implementation deviation, spec gap, or inaccurate test. Implementation deviation → fix code and add tests; spec gap → update spec first; test inaccuracy → correct verification method. Keeping these three categories separate prevents endless patching.

Human review covers what automation misses: code style compliance, architectural boundary violations, permission and data risk handling, user experience alignment with product judgment. Review feedback also loops back to spec or implementation.

Verification Results Must Be Categorized Implementation Deviation: Code doesn't meet spec → fix implementation and add tests. Spec Gap: Spec doesn't cover real path → update spec then continue implementation. Verification Gap: Tests can't prove acceptance criteria → add verification scripts or manual check items.

7. Specification Changes Must Be Co-Managed with Code in the Same Repository

SDD's collaboration impact lands on version control. Spec documents live in the same repo as code, reviewed alongside feature branches. When architecture, database, interfaces, or acceptance criteria change, update the spec first, then drive AI to update implementation.

This reduces "code changed, docs stuck at old version" disconnect. Reviewers see spec diff, code diff, and test results together, judging whether the change still meets original goals.

Spec changes require discipline: wording fixes don't expand implementation scope; new interface fields sync contract and tests; database migrations document compatibility and rollback; acceptance criteria changes add corresponding verification evidence.

Recommended Repository Organization specs/order-export/spec.md : Functional specification and acceptance criteria. specs/order-export/plan.md : Implementation plan, impact scope, risks. specs/order-export/tasks.md : Executable task list and verification tasks. AGENTS.md or similar project rules file: Repo-wide constraints, code style, verification requirements.

8. Adopt SDD Starting with a Medium-Sized Feature

First SDD adoption shouldn't start with a large refactor. Better entry point: a medium-complexity feature with frontend-backend interaction, interface contracts, data constraints, exception paths, and verifiable within a day or two.

Run one feature through the full loop: spec writing, spec review, context injection, AI generation, automated verification, human review, merge. Once the loop works, codify templates into the repo and gradually expand to more modules.

SDD value compounds in second and third development cycles. Reused specs make agents inherit existing constraints easier; newcomers grasp system boundaries faster; reviewers judge boundary violations more easily.

Summary SDD turns requirements, architecture, interfaces, data, acceptance, and boundaries into AI-executable contracts. Spec review happens before AI writes code; goal is to reduce default inferences. Context injection includes spec, project rules, relevant code, and verification plan. Specs and code share a repo; changes update spec first, then drive implementation and verification.