Agentic Coding Tools
Spec-Driven Development with AI Agents: From Vibe to Verified
Spec-driven development means writing a clear specification before an agent writes code: what the feature does, for whom, with which constraints and how success is verified. The spec becomes the shared source of truth for humans and agents, turning loose vibe coding into a predictable process that scales to real products.
What is spec-driven development?
Spec-driven development is a workflow in which a written specification, reviewed by humans, drives planning, implementation and testing by coding agents.
The idea is not new; it echoes classic requirements engineering. What changed is the economics. When an agent can implement a well-described feature in minutes, the quality of the description becomes the main determinant of the outcome. Teams that write specs get consistent, reviewable results. Teams that prompt ad hoc get fast results that drift, contradict each other and are hard to maintain.
Vibe coding vs spec-driven development
Vibe coding is great for exploration and throwaway prototypes; spec-driven development is what you need when code must last.
In vibe coding, you describe what you want conversationally and steer by reaction. That is fast and fun, and it is a legitimate way to explore an idea. But conversational context is lost after the session, decisions are undocumented and the next change may undo earlier assumptions. Spec-driven development captures those decisions in files in the repository, where both future agents and future colleagues can read them.
The three artifacts: spec, plan, tasks
A practical spec-driven workflow produces three layers of documents, each reviewed before the next.
- Spec: the what and why. User stories, behavior, edge cases, constraints, non-goals and acceptance criteria. No implementation details.
- Plan: the how. Architecture decisions, affected components, data model changes, interfaces, risks. The agent can draft it from the spec and codebase; a human reviews it.
- Tasks: a sequence of small, verifiable steps derived from the plan, each with its own tests or checks.
- Implementation: the agent works through tasks one at a time, running tests after each.
- Update: when reality differs from the spec, update the spec rather than letting code and documentation diverge.
What a good spec contains
A good spec is short enough to read in a few minutes and precise enough that two engineers would build roughly the same thing.
- Problem statement and target users.
- Concrete behavior described as scenarios, including error cases.
- Constraints: performance expectations, security and privacy requirements, compatibility.
- Explicit non-goals to prevent scope creep by the agent.
- Acceptance criteria that can be turned into tests.
- Open questions that must be answered before implementation.
Using agents to write specs
Agents are useful spec partners: they ask clarifying questions, find gaps and draft structured documents from rough notes.
A productive pattern is to describe the feature informally, then ask the agent to interview you with questions about edge cases, constraints and acceptance criteria before drafting the spec. Ask it to list assumptions explicitly. The human remains the decision-maker; the agent accelerates the writing and surfaces what you forgot. Product managers can do this as effectively as engineers, which improves collaboration between both.
Tooling and repository conventions
Spec-driven development needs no special tool; a folder of Markdown files and a convention in your context file are enough.
Many teams keep specs in a docs or specs directory, one folder per feature with spec, plan and tasks files. The CLAUDE.md or AGENTS.md describes the workflow: read the spec, follow the plan, do not expand scope, update the task list as you go. Some open-source toolkits and built-in planning modes formalize this further. Whatever you choose, the important part is that specs live in version control and are reviewed like code.
Introducing spec-driven development in your team
Start with one feature, keep the templates lightweight and refine them after each use.
Heavy process kills adoption; a one-page spec template and a short plan are usually enough. neooutput's AI Code Engineers and AI Solutions Architects work spec-driven in client projects and teach the approach in agentic coding workshops for engineers and product managers alike. If you want more predictable results from your agents, a short call can help you set up a workflow that fits your team.
Frequently asked questions
Is spec-driven development just waterfall again?
No. Specs are small, per feature and updated continuously. The goal is clarity before each implementation step, not a big upfront design for the whole product.
Who should write the spec?
Ideally product and engineering together, with an agent helping to draft and find gaps. The person accountable for the feature approves it.
Does every change need a spec?
No. Small bug fixes and trivial changes need only a clear ticket and a test. Specs pay off for features, larger changes and anything with design decisions.
Where should specs be stored?
In the repository, close to the code, for example in a specs or docs folder with one folder per feature. That way specs are versioned, reviewed in pull requests and readable by coding agents.
