Blueprint First, Then Build: Spec-Driven Development in the Agent Era

The most expensive waste of the agent era: elite builders working without a blueprint

Do the math on your last vibe coding project: how many tokens went into actually writing code, and how many went into rework? In my experience, rework eats at least half. And nine times out of ten, the root cause isn't a weak model — it's that you never made your intent clear before work started.

Here's the brutal conversion: when the agent misunderstands the requirement, that's your fault, not its. Agents are the strongest construction crews of our time, but they have one fatal trait — they never question the blueprint. Tell one to "build a nice admin panel" and it will dutifully erect an entire building, and only after it's done do you realize it faces the wrong way. Then you ask it to tear it down and rebuild, and the tokens go up in smoke.

My take: a prompt is a verbal instruction; a spec is a construction blueprint. Verbal instructions are fine for things you can explain in three sentences; anything over an hour of work deserves a blueprint first. Read it backwards and it still holds: if you keep going back and forth with the agent on rework, the problem isn't your prompting technique — it's the blueprint step you skipped.

What a spec that actually drives an agent looks like: five parts, no more

First, two common "fake specs." One is the 50-page requirements document — the agent starts hallucinating by page 10 and invents the rest. The other is prose-style description — "the system should elegantly handle user requests" means nothing to an agent; it will fill every blank with its own imagination.

There is exactly one standard for a good spec: after reading it, every step of the agent's plan can be traced back to a specific line in the spec. If it can't be traced, the spec is scrap paper. Against that standard, a spec needs only five parts:

• Goals and non-goals: two sentences on what this is and what it isn't. Non-goals matter more — they're the agent's brakes. Without them, the agent will keep building features into places you never imagined.
• User stories + acceptance criteria: every story gets Given-When-Then criteria. A story without acceptance criteria gets one invented by the agent, which it will then proudly declare "done."
• Data and API contracts: schemas, fields, inputs and outputs. This is the part the agent won't freestyle on — the more precise, the better. Contracts are the only part of a spec worth writing down to the field level.
• Won't-do list: explicitly name three things you're not doing this time. It's the cheapest insurance against scope creep — ten times cheaper than stopping the agent mid-review.
• Open questions and decision log: park what you're unsure about; write down why for what you decided. A month from now, when you ask "why did we decide this," that line will save you.

A minimal template you can copy verbatim:

## Goals / Non-goals
## User stories (each with acceptance criteria)
## Data & API contracts
## Won't-do list
## Open questions / Decision log

If it fits on one page, don't write two. A spec's length is inversely proportional to its power — an agent's reading comprehension falls off a cliff for documents longer than half its context window.

The loop: Spec → Plan → Task → Verify, in that order

This is the most important section of the article. Spec-driven isn't the formalism of "write docs before coding" — it's a loop, with a clear output and checkpoint at every step:

1. Spec (you write): start with one page. The agent can help polish wording and fill in formatting, but you sign off. Ownership of intent stays with the human — that part is not outsourceable.
2. Plan (agent drafts, you review): have the agent produce an execution plan first; you review the plan, not the code. This is the highest-ROI review there is — reading 20 lines of plan costs a tenth of reading a 2,000-line diff. Disagree with a step? Kill it now, when it's nearly free.
3. Task (slice it small): break the plan into independently verifiable steps, one thing per step, verified as you go. Big leaps are where rework breeds.
4. Verify (against the spec): the acceptance criteria are written into the spec, so the agent can't wiggle out. "It runs" doesn't count; "acceptance criterion #3 in the spec passes" counts.

On top of the loop sit four iron disciplines:

• Plan before code: never let the agent skip the plan and go straight to code. An agent that skips planning is a crew that doesn't read blueprints — the faster it builds, the more expensive the demolition.
• Traceability: every plan step cites its spec line. Steps with no citation either get their spec written or get deleted. A step with no provenance is a scope-creep seed.
• Change the spec first: discover mid-execution that the spec is wrong? Stop, update the spec, then have the agent draft a change plan against the new spec. Never let code and spec drift in opposite directions — that's where tech debt is born, and why nobody dares touch that code three months later.
• Accept against the spec: at demo time, walk the acceptance criteria one by one. "Looks right" doesn't count; "tests right" does.

In the agent era, the human job shifted from writing code to writing specs and reviewing plans. Accept that shift and productivity truly doubles; refuse it and you just get a faster way to burn tokens.

A spec is a living document, not a kickoff ritual

The most common way specs die: written once, dumped into docs/, left to rot while the code sprints in another direction. Three months later, not a single sentence matches, and the spec goes from asset to liability — future readers now have to figure out which lines are lies.

The fix is boring but works: specs live in git, versioned with the code; the standard move for a requirement change is "update the spec first, then have the agent draft a change plan"; the decision log keeps recording why. Spec and code versions always match — that's the floor.

A simple health check: if your spec hasn't been updated in two weeks, it's dead — either revive it or delete it, but don't keep it around lying to yourself. A dead document costs more than no document, because it sells false confidence.

When to skip the spec: being honest about cost

Specs aren't free. Even a one-pager costs 30 minutes. Whether those 30 minutes are worth it depends on the code's lifespan. My rule: code that lives longer than a week deserves a one-page spec; throwaway scripts, exploratory spikes, prototypes you wouldn't mourn — skip it and vibe as fast as you like.

But watch this trap: "let me just whip up a quick prototype to validate the idea" is the most common excuse. Once a prototype survives, it becomes legacy code — and legacy code's scarcest resource is exactly the spec nobody wrote. If you sense even a 30% chance the prototype goes legit, write the one-pager. It's the cheapest insurance you'll ever buy.

One last line: spec-driven isn't slow — it front-loads the rework time. Thirty minutes up front buys back three hours of back-and-forth later. Anyone who can do that math can do this math.