Spec-Driven Development

A publication by Sam Hatoum. SpecDriven is where I document the history, practice, tools, arguments, and open questions around the field that my career has been building toward. I also founded Auto, which is covered here as one participant in the landscape.

The New Workflow ​

Spec-driven development is an approach in which explicit specifications materially guide implementation and verification. Software intent is moving into a more durable medium:

Intent → Explicit Specification → Implementation → Evidence

The category matters because prompts can be disposable, documents can drift, and code alone rarely preserves why a system works the way it does.

You're Already Specifying ​

Every team specifies, even when it does not keep a formal specification.

A whiteboard, user story, prompt, or conversation can contain specification material. None is automatically precise or complete enough to guide a consequential implementation. The problem is that the decisions inside them are often implicit, fragmented, or thrown away.

The whiteboard gets erased. The conversation evaporates. The code becomes the only surviving record, and code can't tell you why something works the way it does. Three months later, nobody knows. You're left reverse-engineering intent from implementation.

The Polaroid Problem ​

Prompt-to-app tools are the Polaroid camera of software development. You point, you shoot, you get something that looks like a photo. It's fast. It's fun. It feels like magic. But try to blow it up to billboard size and you'll see every flaw. The colors aren't true. The composition is fixed. You're stuck with what you got.

An SLR is a different machine. The lens comes off and gets swapped for the right glass. The aperture, shutter speed, and focal length are all under your control. Every setting is a deliberate decision, and the result scales from a wallet print to a billboard without falling apart. The work happens before the shot, not after it.

Spec-driven development is the SLR of software. Maintained specifications expose the settings that matter: what you are building, which choices were deliberate, and what evidence will show whether the implementation behaves as intended.

From disposable prompts to durable specifications ​

Every prompt to an AI contains instructions about what to build. The problem is that a prompt is usually partial, conversational, and easy to lose when the session ends.

Spec-driven development makes the important decisions persistent and inspectable. The intent survives the session. Design and behavior become something people can review, builders can implement, and—where suitable—machines can check against running code.

See the Difference ​

What does spec-driven development actually look like in practice? Current tools, concrete examples, and different relationships between intent, implementation, and checks.

The landscape page tracks what current tools claim, what their public workflows support, and how each relates specifications to implementation and verification. The manifesto states the argument for making product and software decisions explicit before generated code becomes the only surviving record.

See It In Action | Explore the Landscape

Code can be generated. The important decisions still have to be made.

Ready to Take Your Specifications Seriously? ​

The gap between what you meant and what got built is a recurring source of rework and risk. Maintained specifications can narrow that gap when teams treat them as first-class artifacts instead of disposable notes.

Explore the Landscape | Read the Manifesto | See It In Action