# Spec-Driven Development With AI Coding Agents > Write the spec first, then let an AI agent implement against it, so a fuzzy request becomes checkable acceptance criteria instead of guesswork. URL: https://www.matthewswong.com/en/blog/spec-driven-development-ai-agents/ - Author: Matthews Wong (https://www.matthewswong.com/en/about/) - Published: 2026-08-05 - Updated: 2026-08-05 - Category: AI > **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 Trouble With Prompt-At-A-Time Coding 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. - Unstated requirements get filled with the model's default assumptions, not yours. - Prompts are ephemeral, so there is nothing durable to verify the result against. - Each correction is reactive, and drift compounds as the change grows larger. ## What Spec-Driven Development Means With Agents 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. ## The Specify, Plan, Implement, Verify Loop 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. - Specify: describe what to build and what success looks like, in requirements language, not implementation detail. - Plan: pin down the tech stack, architecture, and constraints so the agent is not inventing them mid-task. - Implement: let the agent make focused changes, one reviewable chunk at a time, against the plan. - Verify: check the finished code against the acceptance criteria in the spec, then loop back if it falls short. ## Making The Spec Durable 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. ## Pitfalls And When It Is Overkill 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. - Skip the full spec for a one-line fix or a throwaway script where the intent already fits in the prompt. - Keep the spec lean and current, because a bloated or outdated spec misleads the agent as confidently as a good one guides it. - Reach for the workflow on features with real ambiguity, multiple moving parts, or legacy code where getting the intent wrong is expensive. 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. ## Sources and further reading - GitHub Spec Kit repository - GitHub Blog: Spec-driven development with AI - Claude Code docs: How Claude remembers your project - AGENTS.md open format - Wikipedia: Design by contract ## Source links - https://github.com/github/spec-kit - https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/ - https://code.claude.com/docs/en/memory - https://agents.md - https://en.wikipedia.org/wiki/Design_by_contract ## FAQ ### What is spec-driven development with AI agents? 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. ### How is it different from just prompting an AI to write code? 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. ### What are the steps in the spec-driven workflow? 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. ### Are CLAUDE.md and AGENTS.md files a kind of spec? 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. ### When is spec-driven development overkill? 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. --- - HTML version: https://www.matthewswong.com/en/blog/spec-driven-development-ai-agents/ - Bahasa Indonesia: https://www.matthewswong.com/id/blog/spec-driven-development-ai-agents/ - Site index for agents: https://www.matthewswong.com/llms.txt - Sitemap: https://www.matthewswong.com/sitemap.xml - API description (OpenAPI): https://www.matthewswong.com/openapi.json