Spec-Driven Development: A Practical Guide for AI-Assisted Teams

What spec-driven development actually is

Spec-driven development is a simple commitment: the rules of the system are written down, kept in the repository, and updated whenever they change. Code implements the spec. The spec is not documentation produced after the fact — it is the input.

That sounds like waterfall to people who lived through hundred-page requirements binders, and it is worth separating the two. Waterfall froze the plan and forbade change. Spec-driven development expects change; it just insists the change be recorded in one place rather than scattered across chat threads, tickets, and someone's memory. The spec is versioned like code because it moves like code.

The practice predates AI, but AI is what made it urgent. A human engineer who hits an unwritten rule asks in Slack. An agent hits the same gap and invents an answer — confidently, in fifty files, in under a minute.

Why teams are returning to it now

Three things changed in the last two years:

• The cost of writing code collapsed. When implementation was the bottleneck, ambiguity was tolerable — it surfaced slowly, one developer question at a time. Now the bottleneck is deciding what is correct, and ambiguity surfaces as thousands of lines of confidently wrong output.
• Sessions got shorter than projects. Every agent session starts cold. Whatever context lived in yesterday's conversation is gone unless it lives in a file.
• Review capacity did not scale. Teams can generate far more code than they can meaningfully review. Reviewing intent instead of implementation is the only way that math works.

The five sections that matter

A spec that changes outcomes is structured, not long. Five sections cover nearly everything an implementer — human or agent — would otherwise guess.

Notice what is absent: screens, component names, and file structure. Those are implementation, and implementation is exactly what you want an agent free to choose. Constrain rules; leave layout open.

Writing your first spec in an afternoon

1. List the nouns

Open a blank file and write down every thing your product stores: workspace, project, invitation, document, ticket. For each, list the fields you know and the relationships between them. Do not model perfectly — model honestly. A field you are unsure about is worth a line saying you are unsure.

2. Write the permission matrix

For each entity, answer one question per role: who can see it, who can create it, who can change it, who can delete it. This table is where most security incidents are prevented, and it takes about fifteen minutes per entity.

3. Draw the lifecycles

Any entity with a status column needs its legal transitions written out. "Draft → In review → Approved → Archived; only an owner may approve; approved records cannot return to draft." One sentence removes an entire category of bugs.

4. Enumerate the boring edges

What happens with zero records, with one thousand records, when a parent is deleted, when the same action fires twice, when a token expires? These are the questions that separate a demo from a product, and they are the ones an unaided agent skips most reliably.

5. Define done

Write the observable conditions for each feature. "An owner at the seat cap sees a blocking error before the invite is created" is testable. "Invitations work well" is not.

The economics

The argument for spec-driven development is not craftsmanship, it is cost. Every unwritten decision has three possible fates: it gets asked (cheap, but slow and repeated), it gets guessed correctly (free, unreliable), or it gets guessed wrongly and shipped (expensive, and discovered by a customer).

Writing the decision down converts all three into the first case, once. For a team using AI agents daily, the same handful of rules would otherwise be re-guessed every session — the compounding is real, and it runs against you until the spec exists.

There is a second, less obvious return: review speed. A reviewer reading a spec diff sees "owners may now delete projects" and can approve or reject in ten seconds. The equivalent code review is four files of policy changes that look plausible in isolation.

Common failure modes

Specifying screens instead of rules. A spec full of page descriptions constrains the wrong layer and still leaves permissions undefined. If your spec would not tell you who is allowed to delete a record, it is a wireframe.

Writing it once. A spec that is not updated becomes fiction within two weeks, and a fictional spec is worse than none — agents and new hires both trust it. Make updating it part of the definition of done.

Keeping it outside the repo. A spec in a wiki is a spec the agent cannot read and the diff cannot show. Keep it beside the code.

Over-specifying. If you find yourself dictating variable names, stop. Every sentence should remove a decision that would otherwise be invented incorrectly; sentences that do not meet that bar are maintenance burden.

How this connects to agentic coding tools

If you work primarily through Claude Code, Cursor's agent mode, or a similar tool, the spec is the mechanism that makes each session cumulative instead of a restart. That workflow — where to put the file, how to word the standing instructions, how to scope a session, and what a specified feature request looks like next to a vague one — is covered in detail in our companion piece:

The Claude Code Spec Workflow: Spec-Driven Development for AI Agents — the step-by-step version of this discipline applied to agentic coding sessions, including a worked before-and-after example.

For the wider quality argument, Vibe Coding vs Engineering: the QA gap covers what still needs testing once the spec exists.

Where SpecLoop fits

You can practise all of this in a single markdown file, and on a small project you should. The reason we built the SpecLoop Spec Engine is that the discipline decays under load: specs go stale, the same rule ends up in three places with two different meanings, and nobody can say which version the agent actually read.

SpecLoop generates the deep specification — entities, permissions, states, edge cases, acceptance criteria — in a structured form, versions it as the build progresses, and serves it to coding agents over MCP so the tool reads the current spec rather than a copy pasted last month. The discipline is the one described above. The engine keeps it honest.

The short version

Write down the nouns, who may touch them, the states they move through, what happens at the edges, and how you know you are done. Keep it in the repo, update it after every change, and review at that layer. It is a few hours of work that pays back on the first feature — and every session after that.