It was a Tuesday evening, somewhere around week three of my second AI-assisted project, when I opened the codebase and felt that particular sinking feeling.
The feature worked. The tests passed. The AI had been productive, confident, and fast for three weeks straight. But as I scrolled through the file structure, something was off. The authentication module was built around session tokens — but the product needed JWT-based stateless auth because we'd decided (verbally, in a Slack thread, never written down) that the API would be consumed by a mobile app.
The AI hadn't done anything wrong. It had built exactly what I'd implied. Not what I'd meant.
I closed my laptop, made a coffee, and started counting. How many hours had gone into that auth module? Forty? Maybe fifty across the three weeks? And now it needed to be rebuilt from scratch — not because the AI failed, but because I had never written down what "done" actually looked like.
That was the second time this happened. The third time, I finally stopped blaming the tools and started fixing the real problem.
The Root Cause Isn't Your AI. It's Spec Drift.
Here's the thing nobody talks about in the AI coding space: your AI assistant is not building the wrong thing because it's bad at coding. It's building the wrong thing because you haven't been precise enough about what the right thing is.
Spec drift is what happens when your understanding of the product evolves during development — in your head, in Slack threads, in design reviews — but none of that evolution makes it back into a written, agreed-upon spec. The gap between "what we said in the kickoff meeting" and "what we actually need to ship" grows silently, week by week, line by line.
With a human developer, spec drift is painful. With an AI assistant, it's catastrophic — because AI tools are fast. They don't slow down to ask clarifying questions. They don't have a gut feeling that something seems off. They execute confidently in whatever direction you're pointing, and they do it at ten times the speed of a solo developer. That means when the direction is wrong, you find out further down the road than ever before.
Spec drift isn't a new problem. But AI-assisted development makes it land harder and cost more.
The Checklist Trap
When most developers hear "write a spec," they open a Notion doc and start a bullet list:
- User can log in
- User can view dashboard
- Admin can manage users
- API should be fast
This isn't a spec. This is a wish list.
A wish list tells you what you want. A spec tells you what done looks like, what the interfaces are, what the data model is, what the edge cases are, and what you are explicitly not building right now. The difference sounds semantic until you're three weeks into a rebuild.
The bullet-point PRD gives your AI assistant enough to start. It doesn't give it enough to finish correctly. Every ambiguity in that list becomes a decision the AI makes on your behalf, silently, based on the most statistically likely interpretation of what you meant. Sometimes it guesses right. Often enough, it doesn't.
The problem isn't that developers are lazy. It's that there's been no structured framework for what a "complete" spec actually looks like before you write code. Until now.
Introducing SDD — Spec-Driven Development
SDD is a 17-checkpoint methodology I built after the third time I found myself rebuilding a working codebase because the spec had never been locked down.
The core principle is simple: you do not write implementation code until your spec is complete and verified. Not "good enough." Not "mostly there." Complete.
SDD defines 17 checkpoints organized into phases — from problem definition, through architecture decisions, data modelling, interface contracts, and quality criteria — before you ever write a function.
The Hard Gate
The most important concept in SDD is the Hard Gate at Checkpoint 4.
The Hard Gate is a mandatory stop. Before you pass it, you need three things confirmed in writing:
- The problem statement is unambiguous and agreed upon.
- The success criteria are measurable (not "it should feel fast" — "p95 API response time under 200ms on standard hardware").
- The scope boundary is explicit — what is in this version and, just as importantly, what is not.
If any of those three things are missing or vague, you don't move forward. You go back and sharpen them. The Hard Gate exists because these are the decisions that, if you get them wrong, invalidate every line of code that follows. Everything downstream of checkpoint 4 is built on the foundation you define here. A cracked foundation means a rebuild — regardless of how well the AI codes.
The Hard Gate feels like a delay. It is actually the only thing that prevents a much larger delay at week three.
Walking Through the Checkpoints
Let me show you what a few of these checkpoints look like in practice — and what separates a strong response from a weak one.
Checkpoint 1 — Problem Statement
The question: What specific problem does this product solve, for whom, and why does that person care right now?
Weak response:
"A dashboard for tracking user analytics."
This tells you almost nothing. What kind of analytics? Which users? What decision does this dashboard help them make? Why is it needed now?
Strong response:
"Small SaaS founders (1–5 person teams, <$10k MRR) need a single view of trial-to-paid conversion by acquisition channel, because they're currently piecing it together manually from three tools every Monday morning. This costs roughly 2 hours per week and causes delayed decisions on ad spend. A dashboard that surfaces this automatically reduces that to a 10-minute weekly review."
That response tells your AI assistant — and your future self — exactly what it's building and why. Every subsequent decision gets made in reference to this statement.
Checkpoint 3 — Interface Contracts
The question: What are the inputs and outputs of every major system boundary? What does each API endpoint accept and return?
Weak response:
"We'll have a REST API. Endpoints TBD."
Strong response:
"
GET /v1/metrics/conversionaccepts{ channel: string, date_from: ISO8601, date_to: ISO8601 }, returns{ conversion_rate: float, trial_starts: int, paid_conversions: int, by_day: Array<{ date, rate }> }. Auth via Bearer JWT. Rate limited to 60 req/min per token."
When your AI assistant has this, it builds the right thing. When it doesn't, it makes a plausible guess — which may be architecturally incompatible with the mobile app you're planning to build in month two.
Checkpoint 6 — Data Model
The question: What are the core entities, their fields, their types, and their relationships?
Most developers skip this or do it loosely. The AI then infers a data model from the code it writes — which means the model is shaped by implementation convenience rather than domain logic. This causes subtle bugs that don't surface until you need to write a complex query or migrate the schema.
Weak response:
"Users table, metrics table, probably a channels table."
Strong response:
"Users (id UUID PK, email, plan ENUM[trial, paid, churned], created_at). Metrics (id UUID PK, user_id FK, channel_id FK, date DATE, trials INT, conversions INT). Channels (id UUID PK, name, source ENUM[organic, paid, referral]). Constraint: one Metrics row per user+channel+date combination."
That constraint at the end — one row per combination — is the kind of thing that prevents an entire class of duplicate-data bugs before a single migration is written.
Checkpoint 9 — Explicit Non-Scope
The question: What are you deliberately not building in this version?
This checkpoint sounds optional. It is not. Non-scope is what protects you from feature creep mid-build — and from your AI assistant helpfully adding functionality that wasn't requested.
Weak response:
"We'll keep it simple."
Strong response:
"V1 does not include: real-time data (batch updates only, refreshed hourly), user-level drill-down (aggregate only), export functionality, or multi-account support. These are documented in the V2 backlog. Any prompt that implies these features should be rejected until the spec is updated."
That last sentence matters. When you feed this into your AI context, it becomes a constraint the model actively respects rather than silently overrides.
What This Looks Like in Practice
Once you've completed all 17 checkpoints, you have a document — typically 8 to 12 pages — that serves as the single source of truth for your entire build. You feed it into your AI assistant's context at the start of every session. You reference it when a feature feels ambiguous. You update it through a defined change process rather than a casual Slack message.
The AI's job becomes execution, not interpretation. And execution is exactly what AI assistants are great at.
The methodology works with Copilot, Cursor, Claude, ChatGPT — or with no AI at all. The framework is tool-agnostic because the problem it solves is upstream of every tool.
Start Here — Free
I've packaged the full SDD methodology guide as a free download. No email required. It covers all 17 checkpoints, the Hard Gate criteria, and the quality standards that define "done" for each phase.
If you've ever rebuilt a working feature because the spec was wrong, this is the thing I wish I'd had at the start.
Free : https://saraextreme.gumroad.com/l/ohabsq
If you found this useful, I'd genuinely appreciate a share — I'm trying to get this in front of the developers who need it most.
Tags: #webdev #ai #productivity #programming #softwaredevelopment
Top comments (0)