Spec-Driven Development: Why Living Specs Are the Missing Layer in AI Coding Tools

Every codebase has two layers: what the system does and what the system is supposed to do. Today, we only track one of them.

The intent behind your code — why this API returns that shape, why this page exists, what problem a feature was solving — lives in Slack threads, pull request descriptions, meeting notes, and people's heads. When those conversations scroll away or those people move on, the intent disappears with them.

An AI agent modifying that code six months later has no access to the original intent. It guesses. It breaks assumptions. It rebuilds what already existed. And the developer reviewing its output has no way to evaluate whether the change matches what was originally intended.

This is the problem living specifications solve.

Why Traditional Specs Fail#

Developers have resisted specifications for decades, and for good reason. Traditional specs fail in three predictable ways:

They're tedious to write#

Nobody wants to open a document, write acceptance criteria, list affected files, and maintain a structured format before they can start building. The overhead feels disproportionate to the value, especially for smaller features. So people skip it.

They go stale immediately#

A spec written on Monday is outdated by Friday. The code evolves, requirements shift, edge cases emerge during implementation. But nobody goes back to update the spec. Within weeks, the spec describes a version of the feature that no longer exists.

They're disconnected from code#

Even when specs exist, they live in a separate system — Confluence, Notion, Google Docs — with no link to the actual code that implements them. Developers ignore them because they don't trust them. New team members don't even know they exist.

The result: Most teams have either no specs (and lose intent) or stale specs (and lose trust). Neither outcome is acceptable when AI agents are writing and modifying code at scale.

The Conversational Spec: You Talk, It Writes#

Here's the key insight that changes everything: you're already describing what you want to build before you build it. Every time you prompt an AI coding agent, you're articulating intent — the problem you're solving, the behavior you expect, the constraints you're working within.

That conversation is a specification. It just disappears the moment the context window clears.

What if it didn't?

With a living spec system, the workflow looks like this:

1. You have a conversation with your AI agent about what you want to build. You discuss the problem, explore approaches, define what "done" looks like.
2. You say "create the spec" and the agent generates a fully structured specification — title, description, acceptance criteria, tasks, affected files — from your conversation.
3. The spec is stored in your project, versioned, and accessible to any agent in any future session.
4. Any agent can read it via MCP and understand not just what to build, but why, with what constraints, and how to verify it's correct.

You never open an editor to write a spec. You never manually format acceptance criteria. You never copy-paste between tools. The spec is a natural byproduct of the conversation you were already having.

More Than Code: A Shared Language for Every Stakeholder#

Code is precise, but it's not a shared language. A product manager can't read your React components to understand what a feature does. A QA engineer can't derive test cases from your API routes. A support team member can't explain feature behavior to a customer by reading your codebase.

Living specifications fill this gap because they capture intent in structured, human-readable language:

• Product teams read specs to verify that what was built matches what was requested
• QA engineers use acceptance criteria directly as test cases — they're already written in verifiable terms
• Support teams reference specs to understand feature behavior without asking developers
• Documentation writers use specs as the starting point for user-facing docs
• New developers (and new AI agents) read specs to understand why code exists, not just what it does

This is especially critical in AI-assisted development. When you dispatch an agent to modify a feature, the spec gives it the full picture: original intent, acceptance criteria, technical constraints, and the history of how the feature has evolved. Without this, the agent is working from code alone — and code doesn't explain why it exists.

What Makes a Spec "Living"#

A static spec is worse than no spec. It creates false confidence — people trust it, but it describes a reality that no longer exists. A living spec stays true because the system actively maintains it.

Drift detection#

When commits touch files referenced by a spec, the system flags the spec as potentially stale. You already know which files a spec affects and which commits are linked to it. When new commits modify those files outside the spec's context, that's drift.

Acceptance criteria verification#

For specs with testable criteria — "the API returns paginated results," "the page includes structured data markup," "the form validates email format" — an agent can periodically verify them against the current codebase. Failed checks surface immediately.

Agent-proposed updates#

When code changes are detected, an agent reads the diff, compares it to the existing spec, and proposes updates: modified acceptance criteria, new tasks, updated affected files. The human reviews and approves with a glance, creating a new spec version. The spec evolves with the code, automatically.

Version history#

Every update creates a new version. The original intent is always preserved. You can see how a spec has evolved over time — what was added, what changed, what was removed — and understand why. This prevents feature drift and gives you a complete audit trail from initial intent through every iteration.

The Closed Loop: From Detection to Verification#

The real power of living specifications emerges when you close the loop:

Detect change → Flag spec drift → Agent proposes update →
Human approves → Agent implements → Verify acceptance criteria →
Spec is current

This is the same pattern that works for automated SEO management: scan a site, detect issues, generate structured action items, implement fixes, verify resolution, rescan. Living specs generalize that loop to any kind of development work.

The spec isn't documentation you maintain. It's a feedback loop that maintains itself.

What This Means for AI-Assisted Development#

AI coding agents are powerful but stateless. Each session starts fresh. The context window is the only memory they have, and it's temporary. This means:

• Without specs: Every agent session requires the developer to re-explain context, constraints, and intent from scratch. The quality of the output depends entirely on the quality of the prompt in that moment.
• With living specs: The agent reads the current spec, understands the full context — original intent, acceptance criteria, version history, linked commits — and picks up exactly where the last session left off.

As AI agents handle more of the implementation work, the value of captured intent increases. The spec becomes the durable layer between transient agent sessions — the persistent memory that ensures continuity across any number of agents, sessions, and contributors.

Getting Started#

Living specifications don't require a new process or a cultural shift. They require a system that captures what you're already doing — having conversations about what to build — and keeps that captured intent current as your code evolves.

The workflow is simple:

1. Discuss what you want to build with your AI agent
2. Generate the spec from your conversation (one command)
3. Build with any agent that can read the spec via MCP
4. Let the system detect drift and propose updates as code evolves

No manual writing. No stale documents. No process overhead. Just intent that persists and evolves alongside your code.