What is spec-driven development?

Last updated: August 30, 2026

Spec-driven development is a workflow where you write the specification (requirements, visual mockups, and a technical plan) before an AI coding agent writes any code. The agent builds to a contract instead of improvising from a one-line prompt.

The problem it solves

AI coding agents like Claude Code will build almost anything you ask for, fast. That speed moved the bottleneck: the hard part is no longer can the model write the code, it's did you decide the right thing to build. A one-line prompt lets you skip the decisions that make a feature right: which screens exist, what the edge cases are, what the data model looks like. The agent fills every gap by guessing, silently.

The result is a familiar failure mode: the agent produces something plausible that is subtly the wrong feature, and you discover the decisions you never made in code review, or in production. Spec-driven development front-loads those decisions to the stage where changing your mind costs minutes, not an afternoon of rework.

How spec-driven development works

The loop has a consistent shape regardless of tooling:

1. Requirements first. Write down what the feature is, who it's for, and what "done" means: goals, user stories, and the edge cases you'd otherwise leave to chance.
2. Design before code. Produce reviewable mockups of the screens so you can reject a wrong direction while it's still cheap.
3. Technical plan. Turn the requirements and mockups into a tech spec: data model, file-by-file changes, and an ordered build queue.
4. The agent builds to the spec. The AI agent implements against the plan, mockups, and spec (the same documents you approved) instead of inferring intent from a sentence.
5. Review against the spec. "Does this match what I approved?" is a much easier code review question than "is this what I meant?"

Spec-driven vs. vibe coding

Prompting an agent conversationally, sometimes called vibe coding, is great for exploration, prototypes, and throwaway scripts. It breaks down when the output has to be a specific feature in a real product, because every unstated decision becomes the model's decision. Spec-driven development isn't slower bureaucracy; it's moving the same decisions you'd make anyway from debugging time to planning time.

Running the loop with BuildBoard

BuildBoard is spec-driven development packaged as a local-first macOS app for Claude Code. Each stage is a slash command that produces a reviewable artifact, stored as plain files on your disk:

• /create-feature: writes the requirements plan (Markdown)
• /create-mock: generates HTML mockups you can open and judge
• /create-plan: produces the tech spec and ordered build queue
• /build-plan: sends Claude Code to implement the feature as designed

A kanban board tracks every feature through the five stages (plan, mock, spec, build, ship) so the whole loop stays visible. For a step-by-step walkthrough, see how to plan features for Claude Code.