# Spec-Driven Development for AI Coding (2026)

URL: https://www.devopsness.com/blog/spec-driven-development
Author: Kiril Urbonas
Published: 2026-08-07
Updated: 2026-10-31
Categories: AI
Tags: AI, Spec Driven Development, Coding Assistants, Productivity, Development

Summary: Spec-driven development gives AI coding assistants an unambiguous target, so the output is reviewable, maintainable, and scales past throwaway scripts.

---
# Spec-Driven Development for AI Coding (2026)

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](/blog/what-is-vibe-coding), and it is how you get AI-written code you can ship and maintain.

> [!VERIFIED]
> 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:

1. **Describe intent.** State the goal and the context in a few sentences.
2. **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.
3. **Break into tasks.** Split the spec into units small enough to generate and verify independently.
4. **Generate code per task.** One task at a time, against its slice of the spec.
5. **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](/blog/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](/blog/ai-coding-agents-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](/blog/best-ai-coding-assistants).

## Sources

- [GitHub Spec Kit repository and README](https://github.com/github/spec-kit)
- [GitHub Blog: Spec-driven development with AI, get started with a new open source toolkit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
- [Claude Code docs: Permission modes (plan mode)](https://code.claude.com/docs/en/permission-modes)

