Spec-Driven Development: Write the Spec, Then Let Agents Build
By Tyler Cyert
Spec-driven development is the practice of writing a detailed specification before writing code — then using that spec as the source of truth for both human developers and AI coding agents. Instead of describing what you want in a chat prompt and hoping the AI infers the rest, you write a markdown document that defines goals, constraints, acceptance criteria, and implementation details. The agent reads the spec and builds to it.
This is not a new idea. What is new is that AI coding agents can actually read and follow specs reliably — making spec-driven development the fastest way to get consistent results from tools like Claude Code and OpenCode.
Why Specs Beat Prompts
| Chat Prompts | Spec Documents | |
|---|---|---|
| Persistence | Disappear after the session | Live in your repo, version-controlled |
| Precision | Informal, often ambiguous | Structured with clear criteria |
| Reviewable | Hidden in chat history | Visible in PRs, reviewed by team |
| Reusable | Copy-paste between sessions | Reference across sessions and agents |
| Testable | "Does it look right?" | "Does it meet the acceptance criteria?" |
A prompt gets you started. A spec gets you finished.
What Goes in a Spec
A good spec has five sections:
1. Goals
What are you building and why? One to three sentences. Not a user story — a clear statement of what success looks like.
2. Constraints
What cannot change? What patterns must be followed? What is out of scope? Constraints prevent the agent from making well-intentioned but wrong decisions.
3. Acceptance Criteria
A checklist of specific, testable conditions. Each criterion should be answerable with yes or no. These become your review checklist after the agent finishes.
4. Technical Requirements
Stack, dependencies, file structure, naming conventions, and integration points. Reference your CLAUDE.md for project-wide conventions and add spec-specific requirements here.
5. Implementation Notes
Optional hints about approach. If you know the right algorithm, library, or pattern — say so. Do not force the agent to rediscover what you already know.
A Practical Example
Here is a spec for adding a search feature to a blog:
Goal: Add full-text search to the blog. Users type in a search box and see matching posts filtered in real time.
Constraints: Client-side only, no backend search service. Must work with the existing post data structure. Must not break existing blog list navigation.
Acceptance Criteria: - Search input appears above the post list - Typing filters posts by title and description - Search is case-insensitive - Empty search shows all posts - No results shows a "No posts found" message - Search clears when navigating to a post and back
Technical Requirements: React component in src/blog/, uses existing posts array from posts.ts, Tailwind for styling, no new dependencies.
Implementation Notes: Use a controlled input with useState. Filter with Array.filter on title and description fields. Debounce is unnecessary for a small dataset.
Spec-Driven Development with Claude Code
The workflow is:
- Write the spec in a markdown file. Put it in a
specs/working directory or alongside the code it describes. - Reference the spec in your prompt. Tell Claude Code to read the spec file before starting.
- Let Claude implement. The spec gives Claude enough context to work autonomously.
- Review against acceptance criteria. Walk through the checklist. Mark what passes and what needs iteration.
- Update the spec. If requirements changed during implementation, update the spec. It stays the source of truth.
Specs and Agent Orchestration
Specs become even more powerful in multi-agent workflows, especially when combined with established AI agent workflow patterns. In an orchestrated system:
- The spec author writes requirements into a
specs/working directory - The implementation agent reads from
specs/and writes tosrc/ - The review agent reads from
src/and validates againstspecs/ - The spec is the contract between all three roles
This is how working directories become a file-system contract layer. The spec is the handoff artifact.
Specs vs. CLAUDE.md
| CLAUDE.md | Spec | |
|---|---|---|
| Scope | Entire project | One feature or task |
| Lifetime | Permanent (evolves with project) | Per-task (archived when done) |
| Loaded | Every session automatically | On demand, when referenced |
| Content | Conventions, stack, architecture | Goals, criteria, implementation plan |
Your CLAUDE.md tells Claude how your project works. Specs tell Claude what to build next. They are complementary.
Spec Templates
For features, include goal, constraints, acceptance criteria, technical requirements, and implementation notes.
For bug fixes, include the bug description with reproduction steps, expected vs. actual behavior, root cause analysis (if known), fix requirements, and verification steps.
For refactors, include what is being refactored and why, the before/after structure, migration steps, what must not break, and rollback plan.
Getting Started with Specs
- Create a specs/ directory in your project (or use DotBox to scaffold one as a working directory)
- Write your first spec for your next feature — use the template above
- Add it to your CLAUDE.md — tell Claude where specs live and how to use them
- Start small — one spec per task. Do not try to spec your entire backlog at once.
The best specs evolve with the project. Start writing them and refine as you learn what level of detail your agents need.