Contents
- What Is Spec-Driven Development?
- Why Specifications Work So Well with AI
- Anatomy of a Good Specification: The Template
- The Workflow: Spec-Driven Development in Five Phases
- When Spec-Driven Development Pays Off – and When It Does Not
- Common Pitfalls and How to Avoid Them
- Conclusion
- Frequently Asked Questions
Spec-driven development is an approach in which a written specification becomes the central steering instrument for AI coding agents: first you describe precisely what should be built, then the AI plans and implements on that basis, and finally the result is verified against the specification. This produces traceable, verifiable results instead of lucky hits. This article explains the workflow, provides a template and names typical pitfalls.
What Is Spec-Driven Development?
At its core, spec-driven development reverses the usual way of working with AI. Instead of sending an agent off with a short prompt and iteratively fixing the result, the team first invests in a clear specification. This "spec" describes the goal, behaviour, constraints and acceptance criteria of a feature. It lives as a file in the repository and is versioned and reviewed like code.
The coding agent uses the spec as its binding foundation: it derives a technical plan, breaks it down into tasks, implements them and checks the results against the acceptance criteria. Humans steer at the decisive points – the spec, the plan and the review.
The idea is not entirely new; requirement documents, user stories and test-driven development pursue similar goals. What is new is that the specification is processed directly by a machine and therefore has to be even more precise.
Why Specifications Work So Well with AI
- Less guessing: AI fills gaps with plausible assumptions. A good spec closes those gaps before code is written.
- Better reviews: reviewers check not only "does the code look good?" but "does it meet the spec?".
- Reproducibility: the same spec leads to comparable results when implemented again – important when an agent has to restart a task.
- Documentation as a by-product: months later, the spec still explains why a feature was built this way.
- Better collaboration: product owners, developers and QA work on one shared document instead of scattered tickets and chat threads.
Spec-driven development is therefore a particularly structured form of context engineering: the context the agent needs is captured deliberately and permanently.
Anatomy of a Good Specification: The Template
A practical spec does not have to be long, but it must be complete. This structure has proven itself:
- Goal: which user or business problem does the feature solve? One to three sentences.
- Context: affected modules, existing components, relevant data models.
- Behaviour: what happens in which case? Ideally as numbered rules or scenarios.
- Acceptance criteria: verifiable statements, ideally translatable directly into tests.
- Edge cases and error states: empty input, missing permissions, network errors, limits.
- Non-goals: what is explicitly not part of this implementation.
- Technical constraints: libraries to use, interfaces, performance or security requirements.
- Open questions: what is still unresolved? An agent should stop here rather than guess.
An acceptance criterion such as After more than 5 failed login attempts within 15 minutes, the account is locked for 15 minutes and a notice is shown is unambiguous for both humans and machines. "Login should be secure" is not.
The Workflow: Spec-Driven Development in Five Phases
| Phase | Who leads? | Output | Checkpoint |
|---|---|---|---|
| 1. Specify | Product owner and developers, AI helps draft | Spec file in the repository | Spec reviewed by business and engineering |
| 2. Plan | Coding agent drafts a technical plan | Plan with affected files, data model, interfaces | Developer approves the plan |
| 3. Break down | Agent or developer | Small, individually verifiable tasks | Tasks are small enough to review |
| 4. Implement | Coding agent, tests first | Code and tests per task | Tests pass, diff reviewed |
| 5. Verify | Developers and QA | Check against all acceptance criteria | Spec updated if anything deviates |
The approach works particularly well combined with tests: acceptance criteria are first translated into tests, then implemented. More in agentic coding and test-driven development.
When Spec-Driven Development Pays Off – and When It Does Not
Well suited are features with business logic, interfaces between teams, security-relevant functions, migrations and anything that will need maintenance later. It also helps in projects with external clients because the spec doubles as the basis for alignment.
Less useful are throwaway prototypes, small bug fixes with an obvious cause or exploratory experiments. Here the specification effort would outweigh the benefit.
Common Pitfalls and How to Avoid Them
- Over-specification: specs that prescribe every line of code are hard to maintain. Describe behaviour and boundaries, not implementation.
- Stale specs: if changes only land in the code, the spec loses its value. Make updating the spec part of the Definition of Done.
- Unreviewed specs: a spec drafted by AI but never checked carries errors straight into the code.
- Missing project rules: the spec describes the feature, but cross-cutting conventions belong in project rules. How to write them is shown in project rules and context files for coding agents.
- Oversized specs: an entire module in one spec leads to unwieldy plans. Split it into feature specs.
How requirements are developed with AI support before they become a spec is described in AI in requirements engineering.
Planning an app? Request a free fixed-price quote in 2 minutesConclusion
Spec-driven development makes working with coding agents more predictable, verifiable and sustainable. The specification becomes a shared steering instrument for business stakeholders, developers and AI. The extra effort at the start pays off through less rework, better reviews and living documentation. Teams that want to adopt the approach learn it best on a real feature from their own backlog – for example in a hands-on workshop whose content we agree individually.
Frequently Asked Questions
How does spec-driven development differ from a classic requirements document?
A requirements document usually describes an entire project for humans, whereas a spec in spec-driven development describes individual features precisely enough for a coding agent to implement and verify them directly. It is versioned in the repository.
Can AI write the specification itself?
AI can produce good drafts and point out gaps. However, the domain review and approval of the spec must be done by people.
How long should a spec be?
As short as possible, as complete as necessary. For a typical feature, one or two pages with goal, behaviour, acceptance criteria, edge cases and non-goals are often enough.
Do you need special tools for spec-driven development?
No. Markdown files in the repository and a coding agent that reads them are enough to get started. Some tools also offer their own spec workflows.