Specification-Driven Development

The most common failure mode in AI-assisted development is prompt underspecification. You describe roughly what you want, the model makes reasonable assumptions about the gaps, and what you get back is technically functional but wrong for your context in ways that are tedious to diagnose and fix. Iteration happens — but it’s the wrong kind of iteration: correcting misunderstandings rather than refining genuine decisions.

Specification-driven development addresses this by inverting the process. Write the spec first, with enough detail that the implementation space is genuinely constrained, then execute.

What a Specification Contains

A good spec is not a bulleted wish list. It’s a document that reduces ambiguity to a level where implementation is mostly mechanical.

Requirements: What the feature must do. Stated precisely: “The glossary page should display all terms sorted alphabetically, with each term showing its one-line definition and linking to the full entry page.” Not: “Display glossary terms.”

Constraints: What the implementation must not do, or what it must stay within. File size limits, dependency restrictions, browser compatibility requirements, performance budgets. Constraints are often more important than requirements because they eliminate entire solution classes.

Data model: The shape of the data being handled. Field names, types, required vs. optional, relationships. If the spec says “each glossary term has a domain field that takes one of three values,” the implementation doesn’t need to invent that structure.

File structure: Where new files should live, what existing files get modified, what new components are created. This prevents the model from creating files in unexpected locations or restructuring things that shouldn’t be touched.

Out of scope: Explicit statement of what is not part of this implementation. This matters because models will often add adjacent functionality they think might be helpful. “Out of scope: search functionality, filtering by domain, pagination” removes the temptation.

Examples: Where useful, concrete examples of expected inputs and outputs. For a content transformation function, provide sample input data and the expected output.

Why It Works Especially Well with AI

Human developers read specs and ask clarifying questions. They have the context to recognize when a requirement is ambiguous and flag it before writing code. AI coding assistants don’t reliably do this — they fill gaps with assumptions and proceed.

The result is that vague prompts produce code that technically satisfies the stated requirements while violating unstated ones. The spec is the mechanism for making unstated requirements explicit before they can be violated.

There’s a second reason: specs create a review artifact. After the implementation, you can check it against the spec systematically. Does it handle the edge cases the spec described? Does it stay within the constraints? Does it match the data model? This kind of structured review is much faster than the alternative: reading the code and trying to infer what it was supposed to do.

The Spec-Plan-Implement Pipeline

The workflow has three stages:

Spec: Write the specification document. This is the thinking-intensive phase — most of the hard decisions get made here. If you can’t write a clear spec, you don’t understand the problem well enough to implement it.

Plan: Share the spec with the model and ask for an implementation plan before any code is written. The plan reveals how the model interprets the spec and surfaces misunderstandings cheaply. If the plan is wrong, correct it at the plan stage — not after ten files have been modified.

Implement: Execute the plan. With a good spec and a validated plan, implementation is mostly mechanical. The model has a clear target, the constraints are defined, and deviations from the plan are immediately visible.

How It Differs from Waterfall

Specification-driven development is not waterfall. Waterfall specs are comprehensive upfront designs for entire systems that take months to produce. Spec-driven development uses lightweight specs for individual features — often a single page — written quickly and treated as working documents that can be revised.

The key property is not comprehensiveness but precision. A two-page spec that is precise about the 10 things that matter is more useful than a twenty-page spec full of hedged language and open questions.

Examples from Building This Site

The SEO meta tag system for this site was implemented spec-first. Before any code was written, a spec document defined exactly which tags each page type should emit, what data each tag should draw from, how missing data should be handled, and what out-of-scope SEO features would not be included. The implementation matched the spec closely, and the review was fast because there was a clear target to check against.

The same pattern holds for the content collections: each collection has a documented schema before content is added, which means the implementation matches the schema and the content matches the implementation. No gap between what the system expects and what the data provides.