Derar Sattouf

Spec-Driven Development in 2026: Moving AI Coding Beyond Vibe Coding

AI Development

Spec-Driven Development in 2026: Moving AI Coding Beyond Vibe Coding

Spec-Driven Development in 2026: Moving AI Coding Beyond Vibe Coding

In late 2024 and throughout 2025, "vibe coding" captured developer culture. You opened a chat window with an LLM, described what you wanted in casual prose, accepted the generated code, and iterated by intuition. For weekend hacks, exploratory prototypes, and single-file scripts, vibe coding felt like magic.

Then those prototypes reached production.

As codebases expanded past 10,000 lines and survived multiple release cycles, teams hit what engineers now call the three-month wall. Natural language chat sessions lacked persistence. One agent would optimize a database query using raw SQL; another agent, prompted three days later in a separate window, would rewrite the module using an unoptimized ORM pattern. Subtly, architectural drift set in, edge cases were dropped, and technical debt compounded faster than developers could audit it.

In 2026, the software engineering consensus has matured. AI coding agents are no longer novelty assistants; they are autonomous contributors that execute significant portions of the codebase. But to make agents reliable at scale, engineering teams are replacing exploratory prompt banter with Spec-Driven Development (SDD).

In SDD, code is no longer the primary artifact manually written by humans or improvised by chat prompts. Code is a derivative output generated by agents from precise, version-controlled specifications.

Our earlier articles covered how to structure repository context, working with coding agents as async teammates, and orchestrating automated background agents. This guide explores the next step up: how to write, structure, and execute spec-driven workflows that eliminate hallucinations and turn AI agents into predictable engineering engines.

TL;DR

  • Vibe coding is for discovery; Spec-Driven Development is for production. Conversational prompting is great for greenfield prototyping, but it creates architectural drift and untracked edge cases in production systems.
  • Invert the relationship between code and documentation. The specification is the version-controlled source of truth. The code is compiled by the agent to satisfy the spec.
  • The SDD Pipeline: Every major feature moves through four explicit artifacts: Constitution (global conventions) $\rightarrow$ Specification (requirements and invariants) $\rightarrow$ Plan (architectural blueprint) $\rightarrow$ Tasks (atomic, verifiable checklist).
  • Token economy matters. Giving an agent a 20-page requirement document in one prompt degrades attention. Decomposing specifications into isolated, verifiable task loops keeps agent context windows clean and hallucination-free.
  • Deterministic verification gates: An agent is only allowed to check off a task when machine-checkable criteria—unit tests, typechecks, and linter runs—pass cleanly.

1. Why Vibe Coding Hits the "Three-Month Wall"

To understand why Spec-Driven Development has gained such fierce momentum, look at how pure conversational AI coding fails over time:

[Vibe Coding Loop]
Prompt ──> AI writes code ──> Test visually ──> Re-prompt ──> Commit
   ▲                                                             │
   └────────── Context lost when session resets ─────────────────┘
  1. Context Decay Across Chat Sessions: LLMs do not share memory across separate conversation windows. When a developer opens a new tab on Monday morning to fix a regression, the agent has zero recollection of why a helper function was written with a specific concurrency lock on Friday.
  2. Intent-to-Implementation Drift: When you ask an agent to "make user onboarding faster," it might aggressively cache responses in memory, unknowingly bypassing authentication checks or introducing stale data bugs for multi-tenant users.
  3. Ghost Dependencies and Inconsistent Patterns: Without hard guardrails, an agent might install lodash-es in one file, use native ES6 methods in another, and pull in a redundant date formatting library in a third.
  4. The Review Burden: Reviewing a monolithic 800-line pull request produced by twenty iterative chat prompts is exhausting. The reviewer cannot distinguish deliberate architectural decisions from accidental agent hallucinations.

Vibe coding optimizes for token generation velocity, but engineering organizations care about system maintainability, correctness, and auditability.

2. What Is Spec-Driven Development (SDD)?

Spec-Driven Development reverses the workflow. Instead of prompting an agent to immediately produce TypeScript, Python, or Go code, the developer collaborates with the agent to create a machine-verifiable specification first.

[Spec-Driven Development Pipeline]
1. Constitution (AGENTS.md) ──> Establishes project rules & non-negotiables
2. Specification (spec.md)   ──> Defines functional requirements & invariants
3. Technical Plan (plan.md)  ──> Maps architectural changes & file touched
4. Task Matrix (tasks.md)    ──> Breaks work into atomic, testable steps
5. Agent Execution Loop      ──> Implements task -> Runs tests -> Checks box

In SDD:

  • The human developer acts as the System Architect and Quality Gatekeeper.
  • The specification acts as the Contract.
  • The AI agent acts as the Executor and Test Implementer.

Because the spec lives as Markdown files inside the repository, it benefits from git version control, peer review, and branch isolation.

3. The Four Pillars of the SDD Pipeline

A production-ready spec-driven workflow consists of four structured layers:

Pillar 1: The Project Constitution (AGENTS.md)

Before an agent can read a feature specification, it must know the project's foundational laws. As detailed in our guide on context engineering, this lives in an AGENTS.md file at the root of the repository.

The constitution defines:

  • The canonical tech stack and approved package ecosystem.
  • Forbidden patterns (e.g., "Never use any in TypeScript; never query the database from a React component").
  • Exact build, lint, and test commands.
  • Security boundaries (e.g., "Never expose internal IDs to client endpoints").

Pillar 2: The Feature Specification (spec.md)

When building a new capability, create a scoped directory (for instance, docs/specs/idempotent-webhooks/ or specs/billing-tier-upgrade/). The spec.md outlines what is being built and why, completely independent of low-level implementation details.

A robust spec.md includes:

  • User Scenarios: Precise user stories and background context.
  • Data Invariants: Schema definitions, input validations, and state machines.
  • Edge Cases & Failure Modes: What happens during network timeouts, database deadlocks, or malformed payloads.
  • Acceptance Criteria: Concrete, unambiguous assertions written in testable language.

Pillar 3: The Technical Blueprint (plan.md)

Once the human reviews and approves the spec.md, the AI agent is instructed to produce plan.md. This is where the agent plans the technical execution:

  • Existing files that need modification.
  • New files, schemas, and routes to be created.
  • Database migration strategy.
  • Potential risks and breaking changes.

The developer reviews the plan to verify that the agent's architectural approach aligns with the team's patterns before any code is generated.

Pillar 4: The Task Matrix (tasks.md)

The agent translates the approved plan.md into an ordered, atomic checklist in tasks.md.

Each task must be:

  • Small: Limited to 1–3 files.
  • Self-Contained: Capable of passing tests and typechecks independently.
  • Verifiable: Accompanied by a specific test command.
<!-- tasks.md snippet -->

- [ ] Task 1.1: Create `WebhookEvent` Prisma schema and run migration
  - Verification: `pnpm prisma migrate dev`
- [ ] Task 1.2: Implement Zod payload validation in `lib/webhooks/schema.ts`
  - Verification: `pnpm vitest run tests/webhooks/schema.test.ts`
- [ ] Task 1.3: Implement idempotent deduplication check in Redis
  - Verification: `pnpm vitest run tests/webhooks/dedup.test.ts`

4. Real-World Walkthrough: Building an Idempotent Webhook Engine

Let’s see SDD in practice. Suppose we need to build an idempotent Stripe webhook processing pipeline in a Next.js application with PostgreSQL.

Step 1: Authoring the spec.md

Rather than typing "write a webhook handler that handles stripe idempotently", we author specs/webhooks/spec.md:

# Feature Specification: Idempotent Stripe Webhook Pipeline

## 1. Objective

Ensure all inbound Stripe webhook events are processed exactly once,
even when Stripe delivers duplicate payloads or network retries occur.

## 2. Invariants & Rules

1. Signature Verification: Every incoming payload must be verified with the
   Stripe webhook secret before parsing.
2. Idempotency Key: Store `event.id` in a dedicated `processed_events` table.
3. Concurrency Protection: If two identical event IDs arrive simultaneously,
   only one must process; the duplicate must return HTTP 200 immediately.
4. Transactional Integrity: Business logic execution (account crediting)
   and event status updates must execute inside a single database transaction.

## 3. Failure Modes

- Missing or invalid Stripe signature: Return HTTP 400 immediately.
- Duplicate event ID: Log event as DUPLICATE and return HTTP 200 with `{ received: true }`.
- Downstream database failure during processing: Return HTTP 500 so Stripe retries later.

## 4. Acceptance Criteria

- [ ] Unit test: Rejects payloads missing `stripe-signature` header.
- [ ] Unit test: Rejects tampered payloads.
- [ ] Integration test: Submitting event `evt_100` twice results in exactly
      one database mutation and two HTTP 200 responses.
- [ ] Typecheck: All event handler maps are strictly typed with `Stripe.Event`.

Notice the precision: there is no ambiguity about HTTP status codes, race conditions, or transaction boundaries.

Step 2: The Agent Generates plan.md

We prompt our coding agent:

"Read AGENTS.md and specs/webhooks/spec.md. Draft a technical implementation plan in specs/webhooks/plan.md. Do not write application code yet."

The agent produces a structured architectural roadmap:

# Architecture Plan: Idempotent Stripe Webhooks

## File Changes

1. `prisma/schema.prisma`: Add `WebhookEventLog` table with unique constraint on `eventId`.
2. `src/server/webhooks/verify.ts`: Webhook signature cryptographic check.
3. `src/server/webhooks/processor.ts`: Transactional processor with advisory locks.
4. `src/app/api/webhooks/stripe/route.ts`: Next.js Route Handler.
5. `tests/webhooks/stripe.test.ts`: Vitest test suite.

## Database Migration

Table: `WebhookEventLog`

- `id`: UUID (Primary Key)
- `eventId`: VARCHAR(255) (Unique Index)
- `eventType`: VARCHAR(100)
- `processedAt`: TIMESTAMP
- `status`: ENUM ('PROCESSING', 'COMPLETED', 'FAILED')

Because you can read this in under a minute, you catch architectural flaws before the agent writes hundreds of lines of code.

Step 3: Executing the Task Loop

With the plan verified, the agent works through tasks.md sequentially. The prompt to the agent is straightforward:

"Execute Task 1.1 from specs/webhooks/tasks.md. Run the designated verification command. If it passes, mark the checkbox [x] and pause for review."

The agent:

  1. Creates the migration file.
  2. Runs pnpm prisma migrate dev.
  3. Checks the terminal output for clean exit code 0.
  4. Updates tasks.md to - [x] Task 1.1.

If an error occurs (such as a foreign key constraint conflict), the agent reads the terminal traceback, corrects the migration, and reruns the check. It does not move to Task 1.2 until Task 1.1 is verified.

5. Vibe Coding vs. Spec-Driven Development

Here is how the two approaches compare across core engineering metrics:

| Metric | Vibe Coding | Spec-Driven Development (SDD) | | :------------------------- | :-------------------------------------------- | :--------------------------------------------------------------------- | | Primary Input | Ad-hoc natural language prompts | Version-controlled markdown specifications | | Context Management | Ephemeral chat history (lost on reset) | Persistent file artifacts (spec.md, tasks.md) | | Architectural Drift | High (each prompt introduces subtle variance) | Low (bounded by project constitution) | | Code Review Difficulty | Exhausting (massive monolithic diffs) | Fast & structured (reviewed against task list) | | Tool Compatibility | Locked to a specific chat window or IDE | Universal (works with Claude Code, Cursor, Copilot, custom CLI agents) | | Best Suited For | Spikes, hackathons, single-file scripts | Production apps, multi-developer teams, critical systems | | Failure Mode | Accumulates tech debt at 3 months | Upfront overhead if specs are over-engineered |

6. Practical Rules for Writing High-Yield Specs

To keep SDD productive without drowning in administrative bureaucracy, follow these practical rules:

1. Specify Invariants, Not Implementations

Describe what must hold true, not every single line of code.

  • Weak Spec: "Create a function called calcDiscount that uses an if statement to check if the user is a premium member."
  • Strong Spec: "Users with tier PREMIUM receive 15% off cart totals over $50. Discounts cannot reduce cart value below $0.00. Floating point rounding must round half-up to two decimal places."

The strong spec gives the agent room to use idiomatic code while guaranteeing business accuracy.

2. Include Negative Test Cases

Agents are naturally eager to satisfy the happy path. A great spec spends half its space defining what should not happen:

  • What happens when the JWT has expired?
  • What happens if the payload size exceeds 1MB?
  • What happens if the external API returns a 503 gateway timeout?

3. Keep Specs Co-Located in Git

Do not bury specifications in external tools or ephemeral dashboards where agents cannot access them. Store specs directly in your repository:

my-app/
├── AGENTS.md
├── specs/
│   ├── auth-passkeys/
│   │   ├── spec.md
│   │   ├── plan.md
│   │   └── tasks.md
│   └── billing-stripe/
│       ├── spec.md
│       ├── plan.md
│       └── tasks.md
└── src/

When specs live in the repository, any agent launched in that workspace can read them instantly, and pull requests include both the specification and the implementation diff together.

7. The Hybrid Workflow: When to Vibe, When to Spec

Spec-Driven Development does not mean you can never vibe code again. Senior engineers use a hybrid cadence:

  1. Phase 1: Exploration & Spikes (Vibe Coding) When you don't yet know how an unfamiliar library works or how a complex UI layout should feel, open an exploratory session. Vibe code freely to throw ideas at the screen. Treat this code as disposable research.
  2. Phase 2: Consolidation (Spec Authoring) Once the spike proves the concept, discard the scratchpad code. Write a concise spec.md capturing what you learned, the edge cases you discovered, and the data schema you want.
  3. Phase 3: Production Build (Spec-Driven Execution) Instruct the agent to execute against the spec with full type safety, comprehensive test coverage, and clean commit hygiene.

8. Summary: The Evolving Role of the Software Engineer

The shift from manual typing to AI assistance did not make software engineering obsolete; it elevated the level of abstraction.

In the vibe coding era, developers were tempted to surrender control to conversational prompts, hoping the model would guess their architectural intent. In the Spec-Driven Development era, developers embrace their true high-leverage role: systems thinkers, architects, and specification authors.

By treating specifications as the primary source of truth and AI agents as disciplined compilers of those specs, engineering teams get the best of both worlds: the rapid execution speed of AI combined with the rigor, stability, and maintainability of enterprise-grade software.

Related Reading