AI Spec-Driven Development: The Definitive Architectural Guide

AI coding agents write hundreds of lines in seconds. That is the easy part. The hard part is everything after: reading the code, checking it does what was meant, and keeping the architecture intact when a dozen agent-written pull requests land in a week. Writing code faster does not, on its own, ship better software.

The research says the same thing, with nuance. In three field experiments with 4,867 developers at Microsoft, Accenture and a Fortune 100 company, an AI coding assistant raised completed tasks by 26.08%. But a randomized trial with experienced open-source maintainers, working in large codebases they knew well, found the opposite: with AI tools allowed, tasks took 19% longer.

The gains are also uneven by experience. In the same field experiments, recent hires and junior developers increased output by 27% to 39%, while senior developers gained 8% to 13%.

Spec-driven development (SDD) is how teams get through that dip. It is also the engineering standard we work by at Dataforge, on client projects and on this website. This guide covers the principles, a ten-phase workflow, a reusable spec template, a worked example and the metrics that tell you whether it's working.

What is spec-driven development?

Spec-driven development is an engineering discipline that makes the specification a first-class, version-controlled artifact. The spec is readable by people and parseable by tools, and it is written before the code, not after. In an AI workflow it is the executable contract: it tells the agent what to build, which constraints to respect and how the result will be tested.

How SDD compares to existing practices

SDD doesn't replace TDD or DevOps. It sits above them and connects architectural intent to generated code. Tests still prove behaviour; the spec says which behaviour matters and why.

Six principles of AI spec-driven development

Testable requirements

Every requirement is a statement you can check, not open-ended prose.

Explicit constraints

Security boundaries, latency budgets, thread safety and dependency limits are written down before generation starts.

Small batches

Work in small batches is one of the seven capabilities DORA found to amplify AI's benefits. Specs split features into isolated tasks an agent can finish and a person can review.

Traceability

Requirement → spec assertion → generated code → test. Each link can be followed both ways.

Human governance

Agents propose plans and implementations; engineers approve the design and the merge.

Continuous validation

CI checks, contract tests and static analysis verify the spec against the running system on every change.

The ten-phase SDD workflow

In practice SDD is a pipeline that alternates human direction with agent execution. Filter by who's involved to see where your engineers' time goes: the agent does the volume, people own the gates.

Writing specs that agents can use

A good spec gives an agent enough context to make the right choices without dictating every line. Specify behaviour, contracts and constraints; leave the internal structure to the implementation and the review.

A reusable feature spec template

# Feature specification: [feature name]

## 1. Objective and context
- **Goal**: [1–2 sentences: the business or technical problem this solves]
- **Consumer**: [primary user role or calling service]

## 2. Functional requirements and acceptance criteria
- [ ] **REQ-1**: [one unambiguous statement of behaviour]
  - *AC-1.1*: Given [state], when [action], then [observable outcome].
- [ ] **REQ-2**: [next requirement]

## 3. Constraints (non-functional)
- **Performance**: [e.g. p95 latency < 200 ms at 1,000 RPS]
- **Security**: [e.g. JWT auth; RBAC enforced on the endpoint]
- **Dependencies**: [e.g. reuse the Redis cache; no new npm packages]

## 4. Contracts and data
```json
// JSON Schema or OpenAPI fragment
{
  "type": "object",
  "properties": {
    "order_id": { "type": "string", "format": "uuid" },
    "amount": { "type": "number", "minimum": 0.01 }
  },
  "required": ["order_id", "amount"]
}
```

## 5. Edge cases and errors
- **EC-1**: Duplicate submission (idempotency key).
- **EC-2**: Database timeout mid-transaction → HTTP 503 with the standard error body.

## 6. Testing
- **Unit**: > 90% coverage of domain logic.
- **Integration**: mock the payment gateway (approved, declined, timeout).

From a vague requirement to a measurable one

Most bad agent output starts with a sentence that sounds like a requirement but can't be tested. Rewriting it adds four things the agent would otherwise guess.

Worked example: an order-creation API

Here is SDD on a small backend endpoint in Python with FastAPI and Pydantic: the spec first, then the tests the agent writes from it, then the implementation.

Step 1: the specification

# Spec: order creation endpoint

## Requirements
- Endpoint: `POST /v1/orders`
- Idempotency: require the `X-Idempotency-Key` header.
- Validation: the customer must exist; the order total must be above 0.
- Responses: 201 Created, 400 Bad Request, 409 Conflict on a reused idempotency key.

Step 2: the agent writes the tests first

import pytest
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_create_order_success():
    headers = {"X-Idempotency-Key": "unique-uuid-1234"}
    payload = {"customer_id": "cust_888", "amount": 49.99, "items": ["item_1"]}
    response = client.post("/v1/orders", json=payload, headers=headers)
    assert response.status_code == 201
    assert "order_id" in response.json()

def test_create_order_duplicate_idempotency():
    headers = {"X-Idempotency-Key": "duplicate-uuid-5555"}
    payload = {"customer_id": "cust_888", "amount": 20.00, "items": ["item_2"]}

    # First request
    res1 = client.post("/v1/orders", json=payload, headers=headers)
    assert res1.status_code == 201

    # Same key again
    res2 = client.post("/v1/orders", json=payload, headers=headers)
    assert res2.status_code == 409
    assert res2.json()["detail"] == "Duplicate request processed"

Step 3: the agent writes the implementation

from fastapi import FastAPI, Header, HTTPException, status
from pydantic import BaseModel, Field, PositiveFloat
import uuid

app = FastAPI()

# In-memory idempotency store (see the review notes below)
PROCESSED_KEYS = set()

class OrderRequest(BaseModel):
    customer_id: str = Field(..., min_length=1)
    amount: PositiveFloat
    items: list[str] = Field(..., min_length=1)

class OrderResponse(BaseModel):
    order_id: str
    status: str

@app.post("/v1/orders", status_code=status.HTTP_201_CREATED, response_model=OrderResponse)
def create_order(
    order: OrderRequest,
    x_idempotency_key: str = Header(..., alias="X-Idempotency-Key"),
):
    if x_idempotency_key in PROCESSED_KEYS:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="Duplicate request processed",
        )

    PROCESSED_KEYS.add(x_idempotency_key)
    order_id = f"ord_{uuid.uuid4().hex[:8]}"
    return OrderResponse(order_id=order_id, status="confirmed")

Project structure and context

AI tools find specs when they live in a predictable place. Keep them in the repository, next to the code they describe.

my-application/
├── .spec/
│   ├── ARCHITECTURE.md          # global rules and invariants
│   ├── ADRs/                    # architecture decision records
│   └── features/
│       ├── order-creation.spec.md
│       └── payment-processing.spec.md
├── docs/
│   └── openapi.yaml             # API contracts
├── src/
│   ├── domain/
│   └── api/
└── tests/
    ├── unit/
    └── integration/

Give agents access to your internal context

AI-accessible internal data is one of the seven capabilities in DORA's AI Capabilities Model: connecting AI tools to internal documentation and codebases is what turns a generic assistant into a useful one. When architecture and conventions live only in people's heads, agents fill the gap with plausible, redundant code. Specs in the repository give Claude Code, Cursor or GitHub Copilot the same ground truth your engineers read.

Our current standard at Dataforge

Spec-driven development is how Dataforge works today: it is our company engineering standard, not a pilot. This website follows it too. A specs folder holds the architecture invariants as MUST rules: no hard-coded copy, every page ships metadata and structured data, motion is progressive enhancement. Every non-trivial change starts as a numbered change spec with a goal, a scope, acceptance criteria and the specs it will update. An AGENTS.md file sends every coding agent to the specs before it touches code, and a written definition of done decides when a change is finished. This article went through the same process.

It's also how we run outsourced software projects: you approve the spec, and the price is fixed per milestone against it.

Failure modes and how to avoid them

Specs don't remove every problem. These are the four we see most often when teams scale AI agents.

Metrics: is SDD working?

SDD turns quality control from bug-hunting at the end into continuous verification. Measure it with the delivery metrics you probably already know from DORA, plus two that show the cost of review.

Throughput

Lead time for changes and deployment frequency. Is AI speed reaching production, or piling up in review?

Instability

Change failure rate and failed deployment recovery time. Is generated code causing incidents?

Review effort

Reviewer comments and approval rates per pull request. Does agent code pass review smoothly?

Rework rate

How often you ship unplanned fixes for something you just shipped.

Conclusion

Spec-driven development turns AI coding agents from fast, unpredictable code generators into disciplined members of the delivery pipeline. AI makes raw code cheap; that makes system design, domain modelling and human judgment about trade-offs worth more, not less.

Write testable specs, gate every change with automated checks, keep batches small, and the J-curve gets shallower: you keep the speed and keep the codebase healthy.

The agent writes the code. The spec decides what correct means.

If you want to try SDD on a real project without building the process yourself, book a 30-minute call. We'll show you a spec from one of our projects and tell you honestly whether the approach fits yours.