Spec-Driven Development: Why Your AI Agent Needs a Blueprint

An AI agent can implement a feature in minutes. If the feature is wrong (wrong scope, wrong interface, wrong assumptions) those minutes bought you technical debt at machine speed. You'll spend longer untangling the confident-but-wrong implementation than you would have spent writing a spec.

The spec is the leverage point. Everything downstream is mechanical.

The Problem with "Just Build It"

The vibe coding pitch is seductive: describe what you want, let the AI build it, iterate from there. And for small tasks (a utility function, a config change, a UI tweak) it works great. The feedback loop is tight. Mistakes are cheap to fix.

Scale up and the economics invert.

A 50-line function with a wrong assumption costs 5 minutes to fix. A 500-line module with a wrong assumption costs an hour. A multi-file feature that touches 8 files with a wrong architectural assumption? You're throwing it away and starting over.

The fix is faster specification, not slower generation.

What a Spec Looks Like

Not a 20-page requirements document. Not a UML diagram. A focused artifact that answers four questions:

1. What does this do? One paragraph. If you can't describe it in a paragraph, the scope is too big.

2. What does it interface with? Which files, modules, APIs, or systems does this touch? This is where architectural bugs hide, in the assumptions about interfaces.

3. What does "done" look like? Concrete acceptance criteria. Not "works correctly," that's useless. "Writes output to ./dist/, exits 0 on success, exits 1 on failure, handles missing input with error message." Specific enough to verify mechanically.

4. What could go wrong? A /pre-mortem before implementation. Which edge cases matter? Which assumptions are fragile? Where has similar work broken before?

That's it. Four questions, usually fits in half a page. Takes 10-15 minutes to write. Saves hours of rework.

The Beads Pattern

In my workspace, every unit of work is a bead: a tracked issue with an ID, dependencies, and acceptance criteria.

br create "Add rate limiting to API gateway"
br show <issue-id>
br update <issue-id> --claim

I use br, the Beads Rust client. br ready lists actionable work; the atomic --claim is what prevents two workers from selecting the same issue.

A bead is a contract, not just a ticket. Before any agent touches code, the bead defines:

• Scope: What files and modules are in play
• Dependencies: What must exist before this starts
• Acceptance: How to verify it's done
• Risk: What we've seen break in similar work

The agent reads the bead before implementing. The validation checks the bead after implementing. The spec drives both sides.

RPI: One Plan, Implement, and Fresh Validate Experiment

The RPI name came from Research, Plan, Implement. The current AgentOps contract is narrower: Plan once, Implement once, run Validate in a fresh context, report the verdict, and stop.

fixed intent → Plan → Implement → fresh Validate → report and stop

Research can happen before Plan when the intent needs repository evidence. It is useful context work, not an extra binding verdict or an automatic RPI phase.

Plan is the spec. Decompose the work into beads. Define interfaces. Write acceptance criteria. Run a pre-mortem. This is where the leverage lives. A good plan makes implementation mechanical. A bad plan (or no plan) makes implementation a gambling session.

Implement is the easy part. The agent has a spec, has context, has clear acceptance criteria. Generate the code. Run the checks. Commit or fix.

Validate judges the candidate from a fresh context against the same spec and evidence. A later Learn step may propose a reusable lesson, but validation itself only decides whether the current work is proven.

Beads and the reviewed wiki sit beside this loop. They can inform a later plan; they do not alter the verdict for the current candidate.

The teams that skip straight to Implement are the teams that report "AI coding is slower than doing it myself." They're right about unplanned AI coding. Planned AI coding is faster, and the tax math below is what I measured.

Why Specs Beat Prompts

A prompt is a wish. "Build me a rate limiter" and the AI will build a rate limiter. Maybe it's token-bucket. Maybe it's sliding-window. Maybe it rate-limits per IP. Maybe per user. Maybe it stores state in memory. Maybe Redis. You won't know until you read 200 lines of code.

A spec makes the decisions explicit before generation starts:

## Rate Limiter
- Algorithm: sliding window
- Scope: per API key
- Store: Redis (existing cluster)
- Limits: 100 req/min, 1000 req/hour
- Response: 429 with Retry-After header
- Files: src/middleware/rate-limiter.ts
- Tests: rate-limiter.test.ts

Same feature, same model. The input got sharper, and the output followed.

This is shift-left applied to AI development. The earlier you make decisions explicit, the less rework downstream.

The Planning Tax

"But writing specs takes time." Yes. 10-15 minutes per feature.

The math is rough but consistent in my own issue-tracker history (small sample, my workspace only): unplanned features have taken roughly twice as many iterations to land as planned ones, and each iteration is 15-20 minutes of agent time plus human review.

Unplanned: 0 min spec + (~3 × 18 min) = ~55 min total
Planned:   12 min spec + (~1.5 × 18 min) = ~40 min total

The "tax" pays for itself, and the gap widens with complexity: multi-file features suffer most from missing specs.

The 12 minutes you spend planning pay back the first cycle.

Shared File Conflicts

One lesson that took multiple swarm sessions (and one spectacular 6-agent merge conflict pile-up) to learn: identify shared files during planning, not during implementation.

When multiple agents work in parallel (which is the whole point of multi-agent orchestration) they will collide on shared files. Config files. Index modules. Type definitions. Route registrations.

If you identify these during planning, you can assign them to a single agent or sequence the work. If you discover them during implementation, you get merge conflicts, git index corruption, and wasted cycles.

The spec is where coordination happens. By the time agents are writing code, the coordination decisions should already be made.

The Takeaway

Specs aren't overhead. They're the highest-leverage artifact in an AI-assisted workflow.

Write the spec. Let the spec drive the agent. Let the agent drive the code. Validate against the spec. Feed what you learned back into the next spec.

This is the part that travels. Decide intent and constraints before you let the machine generate, and AI-assisted work gets safe enough to hand to people who don't write code at all. I build the rigor for engineers first, then translate it.

Related

• 12-Factor AgentOps: The 12 operational factors for reliable AI coding
• Devlog #4: The Spec Is the Leverage: The session where spec-driven development clicked
• Getting Started with Vibe Coding: A practical guide to calibrating AI trust
• AI Partner: The same discipline, translated for people who don't write code