Why We’re Using AI Spec-Driven Development

(and You Should Too)

Claude Code is open. The model’s loaded. You could have a functional scaffold in 20 minutes. We know (we’ve done it). And we’ve also spent a few chaotic weeks untangling the confident mess that AI tooling will happily produce when no one tells it what you’re actually trying to build. So this time, we’re starting differently: by writing a strong spec first. Yep, like we did way back in Web 1.0.

What We’re Building (Briefly)

We’re not ready to reveal everything, but here’s context. It’s an AI-first software project with multiple roles, external data connections, and several edge cases. In other words, it’s the kind of project that derails fast without discipline. So we slowed down…intentionally.

What “Spec-Driven Development” Means

We’ve written before about our spec-driven approach, but here’s the short version: the spec is the source of truth, not the code. Most teams draft a product requirements doc (PRD), nod at it twice, and move on as the code slowly drifts away from that original vision. The spec becomes archaeology: “Here’s what we were thinking six months ago.” How quaint: waterfall development.

In contrast, our spec is a living framework. It informs every PR, every AI coding session, every “wait, what are we building again?” moment. It’s not documentation. It’s direction.

Why AI Makes This Essential

AI is exceptional at coding…and terrible at knowing what to code. Give Claude Code or Cursor a tightly scoped problem, and it’ll outcode most junior devs. Hand it something vague, and it’ll deliver a polished, confident wrong answer in minutes.

Garbage in, garbage out, faster than ever.

We’ve also discovered what we call context debt. Every AI coding session starts cold unless you re-feed it state and intent. Without a spec, you end up explaining your architecture, logic, and decisions again and again. Across weeks or teams, that’s real productivity loss.

The spec fixes this. It’s the single artifact you paste into every AI session:
Here’s what we’re building. Here’s why. Here are the rules. Go.

What the Spec Includes

We treat the spec as the backbone of the build. Ours includes:

• Product overview and purpose
• User roles and permissions
• Core data model
• Feature definitions and acceptance criteria
• Integration points and edge cases
• Finalized decisions (and *why* we made them)

That last part (documenting decisions) is crucial. It stops the endless “remind me why we’re doing X?” cycle that burns sprint time.

Writing the spec also forces uncomfortable but valuable questions:

• What happens if the API’s down?
• What if the import chokes on bad data?
• What does “done” look like from the user’s point of view, not the developer’s?

These are load-bearing assumptions. Catch them in narrative form, or you’ll rediscover them in production.

What We (Almost) Got Wrong

Here’s our build-in-public moment. We were wrong about two things before we wrote a single line of code. The spec is why we know that.

The first was a data modeling assumption we’d mentally agreed on without ever saying out loud. Writing it down forced us to actually say it out loud, and immediately one of us went “wait, that breaks if…” It breaks. We fixed it in a document instead of a debugger.

The second was a feature we’d been excited about since the idea stage. Fully designed in our heads. We wrote the user flow out step-by-step and got stuck at step four with no clean path forward. Back to the drawing board (but the drawing board, not the codebase). That’s a very different kind of painful.

That’s the spec working exactly as intended.

The Workflow: Spec → Agent → Code

This is the workflow.

We feed the spec directly into Claude Code, not as context, but as input. Each coding session begins with the relevant spec sections, task details, and explicit constraints. That way, the model codes with full architectural awareness.

The results? Fewer mismatches, less cleanup, and fewer “wait, this doesn’t match that” discoveries later. In essence: the spec becomes the ultimate system prompt.

The Limits (and the Point)

A spec organizes uncertainty. We still mark open questions and unresolved assumptions inside the doc. Some answers won’t appear until we build. But when AI tools try to pull us off track, we can tell whether it’s finding a real flaw or just wandering. That distinction is impossible without a well-articulated baseline.