Spec-Driven Development for AI Coding (2026)
Spec-driven development gives AI coding assistants an unambiguous target, so the output is reviewable, maintainable, and scales past throwaway scripts.
Key takeaways
- Spec-driven development means writing requirements, interfaces, constraints and testable acceptance criteria before an AI assistant generates any code, then verifying the output against that same spec.
- It turns review into a checklist and keeps multi-file work coherent.
- Use it for code you will maintain; skip it for throwaway scripts.
On this page
Spec-driven development means you write the spec first (requirements, interfaces, constraints, testable acceptance criteria), have the AI generate code against it, then verify the output against the same spec. It is the structured counterpart to vibe coding, and it is how you get AI-written code you can ship and maintain.
Verified against
GitHub Spec Kit (specify-cli, current main branch) and Claude Code plan mode, against the github/spec-kit README and the Claude Code permission-modes docs. Checked October 2026.
Ask an AI assistant to "build me a rate limiter" and you'll get something. Whether it's the thing you actually needed is a coin flip. A spec replaces the coin flip with a target.
What spec-driven development means for AI coding
Vibe coding is conversational and improvisational. You describe a vague goal, the model produces code, you eyeball it, you nudge, you repeat. That loop is great for exploration and terrible for anything with real requirements, because there's no fixed target to check the output against.
Spec-driven development inverts the order. You define the target before you generate:
- Requirements: what the code must do, in plain language.
- Interfaces: function signatures, inputs, outputs, data shapes.
- Constraints: performance budgets, dependencies you can and can't use, security rules.
- Acceptance criteria: the conditions that make the work "done," ideally testable.
Then the AI generates against that spec, and you verify the result against the same spec. The document is both the brief and the grading rubric.
Why it works better for real software
Four things change when there's a spec in the loop.
The AI has an unambiguous target. Models are strong at filling in a well-defined shape and weak at guessing your unstated intent. A spec removes the guessing. You stop getting plausible code that solves a slightly different problem than the one you have.
Output is reviewable. Review "does this look right?" is a vibe. Review "does this satisfy these six acceptance criteria?" is a checklist. The second one catches gaps and is something a teammate can do without reading your mind.
It scales to larger tasks. You can't vibe-code a payment flow across eight files and keep it coherent. A spec lets you break big work into tasks that each have their own boundary, so the model isn't holding the entire system in context at once.
You get maintainable code you understand. Because you wrote the spec, you understand the design before a single line exists. The code becomes an implementation of a decision you made, not a black box you inherited from a chat log.
The workflow
The pattern most teams converge on looks like this:
- Describe intent. State the goal and the context in a few sentences.
- Generate a spec and review it. Have the AI draft the spec, then you edit it. This is the step that pays back most. Fixing a wrong assumption here costs a sentence; fixing it after code generation costs a rewrite.
- Break into tasks. Split the spec into units small enough to generate and verify independently.
- Generate code per task. One task at a time, against its slice of the spec.
- Verify against acceptance criteria and tests. Run the tests, check the criteria, iterate on whatever fails.
Tooling is formalizing this. Claude Code's plan mode (claude --permission-mode plan, or Shift+Tab in a session) reads files and writes a plan but blocks source edits until you approve it. GitHub's Spec Kit turns the whole loop into commands: install it with uv tool install specify-cli, run specify init, then step through /speckit-specify, /speckit-plan, /speckit-tasks and /speckit-implement in your agent, reviewing each result. The common thread is a review gate between deciding and doing.
uv tool install specify-cli
specify init my-project --integration copilot
cd my-project
# then, in the agent chat: /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement
A short example
Say you need a retry wrapper. The spec:
## Spec: withRetry(fn, options)
Requirements
- Wrap an async function; retry on rejection.
- Exponential backoff with jitter between attempts.
Interface
- withRetry(fn, { retries = 3, baseMs = 200, maxMs = 5000 })
- Returns the resolved value, or throws the last error after retries exhausted.
Constraints
- No external dependencies.
- Total wait must never exceed maxMs per delay.
Acceptance criteria
- Succeeds on first try: fn called once, no delay.
- Fails twice then succeeds: fn called 3 times, returns value.
- Always fails: throws the final error after `retries` attempts.
- Delay grows per attempt and is capped at maxMs.
Task breakdown:
- Task 1: implement the core retry loop and the success path.
- Task 2: add exponential backoff with jitter and the maxMs cap.
- Task 3: write tests covering all four acceptance criteria.
Each task has an obvious pass/fail. When Task 3 goes green, you're done, and you know exactly why.
Writing a good spec
The spec is the product. A few habits that pay off:
- Scope tightly. Say what's out of scope explicitly. "No persistence, in-memory only" prevents the model from inventing a database.
- Show examples. One concrete input/output pair resolves more ambiguity than a paragraph of prose.
- Name the edge cases. Empty input, timeouts, concurrent calls, malformed data. If you don't list them, the model will pick defaults you may not want.
- State constraints, not just goals. Latency budgets, allowed libraries, and error-handling style all belong here.
Keep humans in the loop at two gates: approving the spec and verifying the result. The AI does more typing; you make the decisions that determine whether the software is correct. That's also where good AI pair-programming tips apply, since a spec turns pairing into a shared contract instead of a running guess.
When to use it
Reach for spec-driven development when the code will live longer than the session: features in a real product, anything touching money or auth or user data, work spanning multiple files, and anything a teammate will review or extend. The upfront spec pays for itself the first time it catches a wrong assumption before it becomes wrong code.
Skip it for genuine throwaway work. A one-off data-munging script, a quick prototype to test a UI idea, a scratch experiment you'll delete by lunch. Writing acceptance criteria for code with a lifespan of ten minutes is pure overhead. That's vibe coding's home turf, and there's nothing wrong with it there.
The failure mode on the other side is a spec nobody reads. A twelve-page spec the model generated and you skimmed is worse than none, because it gives the output false authority. If the spec is too long to review in five minutes, the task is too big; split it. And remember that faster generation does not equal more finished software, a point we make at length in AI coding agents produce more code, not more software.
Questions people ask
What is the difference between spec-driven development and vibe coding?
Vibe coding is conversational: you describe a loose goal, accept what the model writes, and nudge until it looks right. Spec-driven development fixes the target first, with requirements, interfaces, constraints and acceptance criteria written down, and then checks the generated code against that document. Vibe coding optimizes for speed of exploration. Spec-driven development optimizes for code that survives review, handoff and production.
Do I need a tool like Spec Kit to do spec-driven development?
No. A markdown file with the four sections (requirements, interface, constraints, acceptance criteria) and an assistant that can read it is enough. Tools such as GitHub Spec Kit and Claude Code's plan mode add structure: slash commands for each phase and a hard gate before edits. They help teams stay consistent, but the discipline matters more than the tooling.
How long should a spec for an AI coding task be?
Short enough to review in about five minutes, which usually means one screen. The retry example above is roughly 20 lines and fully specifies the behavior. If your spec runs to several pages, split the work into smaller tasks with their own specs. Long specs get skimmed, and a skimmed spec lets wrong assumptions through exactly as vibe coding does.
The call we'd make
Match the method to the code's lifespan. If you'll maintain it, spec it. If you'll delete it, vibe it. Most engineers over-apply vibe coding because the fast feedback feels productive, then pay for it in review and rework once the thing has to survive contact with production.
The pragmatic default: start any non-trivial task by asking your assistant for a spec, not code. Spend five minutes fixing the spec. Then let it build. For a broader look at which tools support this workflow well, see our guide to the best AI coding assistants.
Sources
Cite this article
Kiril Urbonas (2026). Spec-Driven Development for AI Coding (2026). DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/spec-driven-development
[Spec-Driven Development for AI Coding (2026)](https://www.devopsness.com/blog/spec-driven-development) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)
More from AI
Explore more articles in this category
Small Language Models vs LLMs: When Smaller Wins
Small language models now handle most agent steps at a fraction of the cost, so pick per step instead of defaulting to a frontier model.
Shadow Testing and Canary Releases for LLM Changes
A prompt tweak or model bump can quietly wreck answers everywhere. Ship LLM changes the way you ship risky code: gate, shadow, canary, roll back.
GPT-6.1 Sol's 80% Price Cut Rewrites Agentic Coding Math
OpenAI priced GPT-6.1 Sol at a fifth of GPT-6 Astra and called it nearly as good at agentic coding. That claim is now a routing decision, not a headline.
You might have missed
Evergreen posts worth revisiting.