Spec-Driven Development with AI Coding Agents
Spec-driven development with AI coding agents means writing a concise specification before any code is generated: what the feature should do, how it fits the architecture and which tasks implement it. The agent then implements task by task against that spec, and the spec doubles as the checklist for review and testing.
The approach addresses the most common failure of agentic coding: agents filling gaps in vague requests with plausible but wrong assumptions. A spec moves those decisions to a stage where they are cheap to discuss and change. This article describes a lightweight version of the workflow that teams can adopt without heavy process.
Why specs matter more with agents
A human developer who is unsure about a requirement usually asks. Agents often do not; they pick an interpretation and build it convincingly. The larger the task, the more such silent decisions pile up, and the harder the result is to review.
A written spec forces those decisions into the open. It also gives the agent stable context across sessions, lets several tasks proceed consistently and gives reviewers something objective to check against. This is not a return to heavyweight documentation. A good spec for a typical feature fits on a page or two.
The three layers of a useful spec
Many teams separate the spec into three short parts, each answering a different question:
Keep each layer short. Requirements should fit a few bullet points per user story, the design should focus on decisions rather than restating the code, and tasks should be listed in the order they can be implemented and tested. If a layer becomes long, that is often a sign the feature should be split into smaller increments.
- Requirements (what and why): user stories or jobs, acceptance criteria, edge cases, non-goals.
- Design (how it fits): affected components, data model changes, API contracts, error handling, security considerations.
- Tasks (in what order): small, independently testable implementation steps, each with its own done criteria.
The workflow step by step
Agents can help write the spec as well as implement it. The key is human review at each transition:
- Write a short problem statement and the main acceptance criteria yourself.
- Ask the agent to explore the codebase and draft the design section, listing open questions.
- Resolve open questions with product, design or domain experts and update the spec.
- Ask the agent to break the design into tasks small enough to review individually.
- Implement one task at a time, test-first where practical, with the spec in context.
- After each task, check the diff against the spec and update the spec if reality differs.
- When all tasks are done, verify every acceptance criterion and archive the spec with the code.
Want an expert opinion on your product?
Talk to a UX expert or AI Code Engineer — 30 minutes, free, no obligation.
Book a call for freeWriting acceptance criteria agents can verify
Acceptance criteria are the bridge between intent and tests. They work best when they are observable and specific. "Users can reset their password" is too vague. Better: "A user who requests a reset receives an email with a link valid for a limited time; an expired link shows an explanation and a button to request a new one; the old password stops working after a successful reset."
Include the unhappy paths explicitly: empty states, invalid inputs, network failures, missing permissions. Agents rarely add these on their own, and they are exactly where users get stuck. Wording and accessibility expectations belong in the criteria too, because they shape the experience as much as logic does.
Where specs live and how they evolve
Store specs in the repository, for example in a dedicated docs or specs folder, so they are versioned with the code and available to agents. Link them from the related pull requests. Project-wide rules belong in CLAUDE.md or AGENTS.md instead; specs describe individual features. See writing CLAUDE.md and AGENTS.md for the distinction.
Specs should change when you learn something during implementation. An outdated spec misleads future agents and colleagues. As a rule of thumb, if the code and the spec disagree after a task, fix one of them before moving on.
Agents can also help keep specs current: at the end of a task, ask the agent to compare the implementation with the spec and list differences. A human then decides which side to adjust.
When spec-driven development is overkill
Not every task needs a spec. Small bug fixes, copy changes and well-understood refactors work fine with a clear prompt and a test. Use a spec when a task touches several components, involves product decisions, changes data models or will take more than one agent session.
Specs are also valuable when handing an AI-built prototype to engineering. Writing down what the prototype actually does, and what it should do, often reveals gaps before production work starts. Related reading: scaling an AI-built MVP and testing strategies for AI-generated code.
Learning the workflow
Spec-driven development is a core exercise in the agentic coding workshops offered by the UXreviewer.io team. Participants write a spec for a real feature from their backlog, have an agent implement it in tasks and review the result against the criteria. Because the team also includes UX and psychology experts, user-facing acceptance criteria get proper attention. Book a call for free to discuss a session.
Frequently asked questions
Is spec-driven development the same as waterfall?
No. Specs here are short, written per feature and updated during implementation. The goal is clarity for each piece of work, not a fixed plan for an entire project.
Can the agent write the spec itself?
It can draft large parts, especially the design and task breakdown, based on the codebase. Humans should own the requirements and approve each layer before implementation starts.
Which tools support spec-driven development?
Any capable coding agent can follow the workflow with plain Markdown files. Some tools and IDEs offer built-in spec or planning modes as of late 2026, but the method does not depend on them.
How detailed should a task in the spec be?
Detailed enough that its result can be reviewed and tested on its own. If a task's diff would be too large to review carefully, split it further.
Book a call for free
From UX audits and Agentic UX reviews to AI development, agentic coding workshops and publishing your AI-built app on the App Store and Google Play — we help you ship. 24/7 call support in English and German.