---
id: "concept-spec-driven-development"
type: "concept"
source_timestamps: ["00:08:50", "00:10:23"]
tags: ["software-engineering", "best-practices", "ai-agents"]
related: ["concept-comprehension-gap", "action-write-specs-first", "entity-amazon", "quote-spec-becomes-eval", "prereq-evals", "framework-dark-code-solution"]
definition: "A methodology where detailed human-written specifications are required before AI code generation, serving as both the architectural blueprint and the evaluation criteria."
sources: ["s23-amazon-16k-engineers"]
sourceVaultSlug: "s23-amazon-16k-engineers"
originDay: 23
---
# Spec-Driven Development

## Definition

**Spec-Driven Development** is a methodology where detailed human-written specifications are required *before* AI code generation. The spec serves a dual purpose: architectural blueprint *and* evaluation criteria.

## The Core Move

Instead of:

> Vague prompt → AI output → human reviews output

Do:

> Detailed human spec → AI generates against spec → AI output validated against spec-as-eval

## Why It Works

1. **Forces comprehension before generation.** The human cannot write a precise spec without first understanding the architecture they intend to create. This closes the [[concept-comprehension-gap]] *upstream*.
2. **The spec becomes the eval.** A clearly written specification translates directly into measurable test criteria the AI must satisfy. See [[quote-spec-becomes-eval]] for the speaker's distillation.
3. **Constrains AI to human intent.** When the AI is bounded by a spec the engineer authored, drift into [[concept-dark-code]] becomes structurally harder.

## Industry Validation

After a major outage in December, [[entity-amazon]] rebuilt their AI coding tool around Spec-Driven Development, leading by turning prompts into strict requirements, tasks, and task lists before any code is generated.

*Note: the Amazon case is asserted by the speaker but not independently verified in the enrichment overlay. The underlying principle — making specs the evaluation criteria — is corroborated by the Stanford HAI validation framework. See [[entity-org-stanford-hai]].*

## Prerequisites

Understanding [[prereq-evals]] is essential — the entire methodology rests on the engineer's ability to translate a spec into an executable evaluation.

## Related Action

Operationalized via [[action-write-specs-first]].

## Where It Sits in the 3-Layer Defense

Layer 1 of [[framework-dark-code-solution]].


## Related across days
- [[concept-spec-quality-bottleneck]]
- [[concept-intent-engineering]]
- [[concept-machine-readable-okrs]]
- [[action-write-specs-first]]
- [[concept-specification-engineering]]