What is spec-driven development, and how does it differ from a requirements doc?
Spec-driven development (SDD) makes a structured, versioned specification the primary artifact your team and your AI coding agents build from. Unlike a requirements doc that ages quietly in a wiki, an SDD spec is executable context: it drives planning, code generation, and tests. When behaviour must change, you edit the spec first and let the implementation follow.
The difference is authority and lifecycle:
- ▸A requirements doc describes intent once, then diverges from the code the moment the first pull request merges.
- ▸An SDD spec stays load-bearing. It lives in the repository next to the code, moves through review, and is regenerated against on every change.
- ▸It is layered, not monolithic, a plain-language intent file, a concrete design, a granular task list, and machine-checkable contracts such as OpenAPI schemas and acceptance tests.
SDD is not new in spirit; behaviour-driven development and design-by-contract shared the same instinct. What changed is that agents can now consume a spec directly and produce most of the code, so the spec finally pays for itself.
Why is the spec becoming the source of truth instead of the code?
Because AI agents now write a large share of production code, and that code is cheap, disposable, and inconsistent between sessions. The durable asset is the intent behind it. When the spec is authoritative, you can regenerate an implementation, review it against a stable reference, and keep humans arguing about behaviour rather than line-by-line diffs.
Consider what happens when code is the only record:
- ▸Intent is reverse-engineered from whatever the model emitted, including its mistakes.
- ▸Two agents given the same vague prompt produce two different architectures, and neither is written down.
- ▸Onboarding means reading code to guess at decisions nobody recorded.
When the spec is the source of truth, the code becomes a build output. You still test, review, and own it, but the argument that matters happens at the spec, where it is cheap to change. Public reporting through 2025 and 2026 consistently shows AI-assisted commits rising sharply; the teams that stay sane are the ones that moved their review effort upstream to intent.
How does spec-driven development stop vibe-coding drift?
Vibe-coding, prompting an agent until something runs, drifts because each prompt is ad hoc and the context evaporates between sessions. SDD anchors every change to a written spec and a task list the agent must satisfy, so intent survives across sessions, contributors, and model versions instead of living in one person's chat history.
The failure pattern is familiar: a feature works in a demo, nobody can explain why, and the next change breaks it silently. We unpack that in Vibe Coding Is Not Engineering: The 2026 Reckoning. SDD is the constructive answer:
- ▸Every task traces to a spec clause, so the agent has a target instead of a vibe.
- ▸Regeneration is safe because the spec, not the last chat, is authoritative.
- ▸Review has an anchor, reviewers check the spec and the tests, not just whether the code runs.
Drift does not disappear; it becomes visible and reviewable.
What does an executable spec actually contain?
An executable spec is layered: a high-level intent document, a concrete design, and machine-checkable contracts. In practice that means a requirements file in plain language, a design file, a granular task list, and formal artifacts, OpenAPI 3.1 schemas, JSON Schema, Gherkin scenarios, and tests, that a machine can verify rather than merely read.
A workable structure many teams converge on:
- ▸requirements.md, user-visible behaviour, acceptance criteria, and explicit non-goals.
- ▸design.md, chosen architecture, data model, key trade-offs, and Architecture Decision Records (ADRs) for anything contested.
- ▸tasks.md, an ordered, checkable task list the agent works through.
- ▸Contracts, OpenAPI 3.1 for HTTP, JSON Schema for payloads, Protobuf for gRPC, Gherkin and Cucumber for behaviour, and Pact for consumer-driven contract tests.
- ▸Executable checks, the acceptance tests and schema validations CI runs, so "the spec passes" is a real, mechanical statement.
For genuinely critical logic, a payment state machine, a permission model, formal tools such as TLA+ or Alloy let you check the design before a line of code exists. That complements the testing strategy that survives refactoring.
Which tools support spec-driven development in 2026?
The tooling landscape is young but real. GitHub Spec Kit, Amazon Kiro, and spec-centric platforms push a spec-first workflow, while Claude Code, Cursor, and GitHub Copilot read repository context files. Formal-methods and contract tools cover the parts that must be provably correct. No single tool owns the category yet, so pick for your stack.
The current field, roughly grouped:
- ▸Spec-first workflows, GitHub Spec Kit (open source, with specify, plan, and tasks steps), Amazon Kiro (an agentic IDE that generates requirements.md, design.md, and tasks.md), and emerging spec registries.
- ▸Agent context conventions, CLAUDE.md, the increasingly common AGENTS.md file, and Cursor rules give agents durable, repo-level instructions instead of per-prompt guesswork.
- ▸Contracts and config, OpenAPI 3.1, JSON Schema, Pact, and typed config languages such as CUE and Pkl.
- ▸Formal methods, TLA+ and Alloy for logic you cannot afford to get wrong.
Treat these as complementary. A realistic 2026 setup is Spec Kit or Kiro for the authoring loop, an AGENTS.md at the repo root, OpenAPI plus Pact in CI, and TLA+ reserved for the two or three areas that genuinely warrant it.
How do you adopt SDD without slowing your team down?
Start narrow. Apply SDD to one greenfield service or one high-risk change where the intent is genuinely contested, not to every CRUD ticket. Keep each spec small enough to review in a single sitting, store it in git beside the code, and let the agent regenerate. Treat the spec, not the diff, as the pull request that matters.
Practical guardrails:
- ▸Right-size the spec. A four-line change does not need a design document. Reserve the ceremony for contested or risky work.
- ▸Put specs in the repo and in CI. Validate OpenAPI, run contract tests, and fail the build when code and spec disagree, the same discipline as a good software requirements document that ships.
- ▸Review the spec first. Move senior attention upstream; a wrong spec caught early is far cheaper than a wrong merge.
- ▸Keep ADRs short. One page per decision beats a forgotten wiki.
The goal is not more documents. It is fewer arguments held late and more decisions written down once.
What are the limits and failure modes of spec-driven development?
SDD is not a silver bullet. Over-specified documents become their own maintenance burden; under-specified ones let agents hallucinate. Specs drift from code exactly like stale comments unless CI enforces the link. And a spec that faithfully encodes a bad design still ships a bad design, SDD improves fidelity, not judgement.
Watch for these:
- ▸The verification gap. An agent can claim it satisfied the spec without actually doing so. Only executable tests make compliance real.
- ▸Spec rot. Without CI enforcing spec-to-code alignment, the spec becomes another lie in the repo.
- ▸Security is not implied. Generated code still needs review; SDD does not remove the risks in the hidden risks of shipping AI-generated code to production.
- ▸Over-formalisation. Not everything deserves TLA+. Most features need a schema and a few tests, nothing more.
Used with judgement, SDD turns intent into a durable, checkable asset. Used dogmatically, it just relocates the bureaucracy.
How TuniCyberLabs helps
We build software the way SDD assumes you will maintain it: specs in the repository, contracts enforced in CI, agents scoped to a written target, and human review moved upstream to intent. Our engineers stand up the authoring loop, wire OpenAPI and contract tests into your pipeline, and reserve formal methods for the logic that earns it, so AI accelerates delivery without eroding correctness.
Want a spec-driven workflow that fits your stack rather than a tool demo? Talk to our engineering team.