AI
Spec-Driven Development With AI Coding Agents
August 20268 min read
It is a workflow where you write a clear specification before implementation, then have an AI coding agent build against that spec instead of coding one prompt at a time. The spec is a durable, checkable artifact that the agent references and that you verify the finished code against.
A prompt is disposable and scrolls out of context, so it leaves nothing to verify the result against. A spec is a written source of truth the agent keeps re-reading and a human reviewer can diff, which turns a vague request into explicit acceptance criteria.
The common loop is specify, plan, implement, verify. You describe what to build and what success looks like, pin down the stack and constraints, let the agent make focused reviewable changes, then check the code against the acceptance criteria and loop back if it falls short.
Yes, they act as living project-level specs. Claude Code reads CLAUDE.md at the start of every session as standing context, and AGENTS.md is an open format many agents read for build commands and conventions. Both give agents durable instructions rather than one-off prompts.
For a one-line fix or a throwaway script, the intent already fits in the prompt and a full spec costs more than it saves. Reach for the workflow on features with real ambiguity, many moving parts, or legacy code where getting the intent wrong is expensive.
Key Takeaway
Spec-driven development is a workflow where you write a clear specification first, then have an AI coding agent implement against it. The spec becomes durable context the agent keeps referencing, turns a fuzzy request into checkable acceptance criteria, and makes review and verification possible instead of trusting one prompt to produce correct code.
AI coding agents are fast, and that speed hides a problem. When you feed an agent a one-line prompt, it fills every gap you left unstated with its own best guess. The output usually compiles and often looks right, but the parts you never spelled out are exactly the parts that come back wrong.
Spec-driven development flips the order. Instead of prompting your way toward a result one message at a time, you write the specification first, then point the agent at it. This post walks through why that produces better results with agents, the specify-plan-implement-verify loop, and when the extra structure is not worth it.
The GitHub team calls the default mode vibe coding: you describe a goal, the agent returns code that looks plausible, and you discover later that it does not quite work. Their framing is blunt. Models are exceptional at pattern completion but they cannot read your mind, so a vague prompt forces the model to guess at requirements you never wrote down.
The deeper issue is that a chat prompt is disposable. It scrolls out of the context window, it is never reviewed, and it leaves no artifact to check the finished code against. You end up steering a moving target, correcting each surprise as it appears, with no shared definition of done that you and the agent both agreed on before work started.
Spec-driven development means you produce a written specification before implementation, and that document becomes the source of truth the agent works from. GitHub's framing is that the spec is a living, executable artifact rather than a paragraph you throw away once coding begins. The agent reads it, plans against it, and you check the code against it.
This works well with agents for a concrete reason: the spec is durable context. An agent keeps re-reading it across a long task, so intent survives even as the conversation history is trimmed. It also converts a fuzzy request into explicit acceptance criteria, which is what makes review and verification possible at all. The idea echoes design by contract, where a component's obligations and guarantees are written as precise, verifiable specifications rather than left implicit.
Keep the spec in a file in the repo, not in the chat box. A committed spec is something the agent can re-read on demand and something a human reviewer can diff, which a scrolled-away prompt can never be.
Toolkits in this space converge on the same four moves. GitHub's Spec Kit, an open-source toolkit for spec-driven development, structures the flow as distinct commands, and the underlying loop is easy to run by hand in any agent even without a tool.
A spec earns its keep when it outlives a single session. Persistent instruction files do this at the project level. Claude Code reads a CLAUDE.md file at the start of every session as standing context, and the AGENTS.md convention, an open format adopted across many coding agents, gives tools a predictable place to find build commands, conventions, and project rules. These act as a living spec for how the codebase expects work to be done.
The best acceptance criteria are concrete enough to verify. The Claude Code memory guidance makes the point plainly: write use 2-space indentation rather than format code properly, and run the test command before committing rather than test your changes. A criterion you can mechanically check is one an agent can satisfy and a reviewer can confirm. Vague ones just move the guessing to a later step.
A persistent instruction file is context, not enforcement. The agent reads it and tries to follow it, but there is no guarantee of strict compliance, so anything that must always hold belongs in a real check like a test, a linter, or a commit hook.
Spec-driven development has failure modes of its own. An over-specified document is as brittle as a vague prompt: it goes stale the moment the code moves past it, and a spec that contradicts itself lets the agent pick whichever half it likes. And for genuinely small work, the ceremony costs more than it saves.
Spec-driven development is not extra bureaucracy for its own sake. It gives an AI coding agent durable context to work from, turns a vague ask into criteria you can actually verify, and replaces reactive correction with a spec both sides agreed on first. Write it down, point the agent at it, and check the result against it.