Spec-Driven Development (SDD)

1. Concept Overview & Systemic Problem

The most common mistake among novice developers in vibe coding is the "Prompt-and-Pray" approach (writing a vague prompt in chat and hoping the model guesses the architecture). When the prompt sounds like "Implement billing via Stripe for subscribers," the model randomly selects database schemas, uses outdated libraries, ignores webhooks, forgets about idempotency, and does not consider edge cases for payment cancellations. When the engineer asks to fix a bug, the model frantically patches holes, ultimately turning the codebase into spaghetti code (AI Slop).

Spec-Driven Development (SDD) is an engineering discipline that separates the system design phase from the code generation phase. Before touching the codebase, a formal specification document (spec.md or RFC.md) is created. This document becomes the Single Source of Truth and the contract against which the agent executes and verifies each subsequent step.

2. Architectural Taxonomy & Mental Model

The architectural framework of SDD is built on a clear hierarchy of design artifacts:

┌─────────────────────────────────────────────────────────────┐
│             SPEC-DRIVEN DEVELOPMENT ARTIFACT HIERARCHY      │
├─────────────────────────────────────────────────────────────┤
│ 1. Product Context: User Problem and Business Goal           │
├─────────────────────────────────────────────────────────────┤
│ 2. Technical Contracts:                                     │
│    • Data Schemas (Drizzle / Prisma schemas, SQL DDL)      │
│    • API Contracts (Zod Schemas, OpenAPI, TypeScript types) │
│    • Invariants & Security Rules (Idempotency, RBAC, Auth)  │
├─────────────────────────────────────────────────────────────┤
│ 3. Atomic Task Checklist (DAG):                             │
│    • Step 1 ➔ Step 2 ➔ Step 3 (Strict Order of Dependencies)│
├─────────────────────────────────────────────────────────────┤
│ 4. Verification Predicates: Machine Readiness Criteria      │
└─────────────────────────────────────────────────────────────┘

1. Technical Contracts (Interface-First):
   • Describes system interactions before the implementation of internal logic. Request/response structures, validation schemas, and error states are defined.
2. Atomic Task Graph (Task Decomposition DAG):
   • The task is broken down into a sequence of small, independently verifiable subtasks. Each subtask should modify no more than 1–3 files.
3. Machine-Verification Criteria (Acceptance Predicates):
   • Instead of subjective "check that everything works," the specification contains specific verification commands: "pnpm test auth.test.ts passes successfully, branch coverage > 90%."
4. Lifecycle Tracker:
   • The specification contains interactive checkboxes ([ ] ➔ [x]), which the agent updates after executing and verifying each step.

3. Technical Pipeline & Internal Mechanics

The development lifecycle under the SDD methodology:

1. Interviewing and Specification Synthesis (Interview Phase): The engineer formulates the task. The model asks clarifying questions about non-trivial details: what behavior is expected during a network break, how to handle duplicates, what rate-limiting thresholds apply.
2. Specification Documentation in Repository: An artifact (e.g., .specs/004-billing-integration.md) is created and added to the Git version control system.
3. Human Audit and Approval (Spec Approval): The engineer reviews the proposed data schemas and contracts. If the architectural solution has flaws, they are corrected at the specification text level in 2 minutes, avoiding hours of code rewriting.
4. Step-by-Step Delegation to the Agent: The agent is called to implement a specific step from the specification:
   • The agent reads the specification context.
   • Writes tests according to the contracts (TDD).
   • Implements functionality.
   • Runs tests and records the execution of the subtask.
5. Final Verification and Archiving: Once all specification items are marked as completed, a thorough audit is conducted, and the specification remains in the repository as living documentation of the feature.

4. Production Engineering Scenarios

01. Development of a Critical Payment Module with Idempotency

Before writing the payment gateway integration code, the engineer creates a specification:

• Documents the structure of the idempotency_keys table with fields key, response_payload, status, expires_at.
• Describes the exact behavior algorithm for receiving a duplicate webhook with a similar transaction_id.
• The agent implements the module strictly according to the specification; no edge cases are overlooked.

02. Parallel Work of Backend and Frontend Agents

The team creates a new analytics dashboard:

• Initially, the specification describes Zod schemas and TypeScript interfaces for all charts and metrics.
• The frontend agent uses these schemas to layout components with mock data.
• The backend agent simultaneously implements real SQL queries and API routes under the same contract.
• Integration occurs without any type incompatibility conflicts.

03. Secure Scalable Migration of a Legacy Module

Replacing the old custom authorization with Better Auth:

• The specification describes maintaining backward compatibility of sessions in Redis and a step-by-step plan for migrating password hashes from bcrypt to Argon2id.
• The agent breaks the migration into 7 isolated stages, each tested separately.

5. Pitfalls, Common Mistakes & Security

• Over-Engineering Paralysis: Writing a 20-page specification for a minor fix like changing button color is a pointless waste of time. Apply SDD for tasks that affect more than 2 modules or contain critical business logic.
• Spec Rot: If a need arises to change a schema during development, engineers often fix the code directly, forgetting to update spec.md. This confuses subsequent agents who will read the outdated specification.
• Using Vague Formulations: Phrases like "the system should work fast" or "ensure reliability" are catastrophic for AI. The specification must operate with concrete values: "p99 response time < 150ms," "return HTTP 429 when exceeding 100 rpm."
• Ignoring Specification Versioning: Specification files must be part of the Git repository alongside the code, allowing tracking of the evolution of architectural decisions through commit history.