Vibe Coding Was the Easy Part. Now You Need Spec-Driven Development.

Last quarter we shipped faster than ever. AI wrote somewhere around 40% of the code. Velocity metrics looked great. The CEO loved the demo.

Then someone had to add a feature to the codebase.

It took four days to understand what two of those AI-generated files even did. There were no comments, inconsistent patterns across modules, and three different approaches to the same problem scattered across the repo — each generated in a separate session, each locally "correct," collectively a mess. The test coverage was high because the AI was great at writing tests. The tests just weren't testing the right things.

This isn't a horror story. This is Tuesday in 2026.

The Productivity Paradox Nobody Wants to Admit

Here's the number that should bother you: experienced developers are 19% less productive when using AI coding tools, according to recent research. Not beginners — experienced devs.

Meanwhile, 93% of developers use AI tools. So most of your senior engineers are quietly struggling while your velocity metrics look fine.

The reason isn't that AI writes bad code. It writes decent code, fast. The reason is that AI writes disconnected code. Each session starts from a blank context. There's no shared understanding of why a system is structured the way it is, what the constraints are, or what decisions were made three sprints ago. Every AI-generated module is optimized for its own session, not for the system it lives in.

The industry has a name for the pattern that's supposed to fix this: Spec-Driven Development.

What Spec-Driven Development Actually Is

Spec-Driven Development (SDD) is the practice of writing structured specifications before you write code — and then handing those specs to AI agents as their operating context instead of ad-hoc prompts.

It's not waterfall. You're not writing a 200-page requirements document before touching a keyboard. It's three lightweight artifacts per feature:

Requirements doc — what you're building and why. User-centric. Written like a PRD.
Design doc — how it works technically. System boundaries, data models, decisions made.
Task list — ordered implementation steps. Each task is atomic enough for one AI session.

The AI agent reads all three before it writes a line of code. Its context isn't a prompt — it's a system. It knows the constraints. It knows what's been decided. It doesn't invent patterns from scratch.

VIBE CODING Idea "make it work" → AI Prompt one big session → Code no shared context → Maintenance nightmare begins

SPEC-DRIVEN

The key word is living. The spec isn't written once and archived. When the AI discovers something the design didn't account for, you update the design doc. When the implementation reveals a better way to sequence tasks, you update the task list. The spec is the source of truth — not the codebase, not the Slack thread, not someone's memory.

The Tools That Actually Do This

Two tools landed in early 2026 and are now the main ways teams implement SDD in practice.

Kiro (AWS)

Kiro is an AI IDE — a fork of VS Code — that builds SDD into the development loop. You describe what you want to build. Kiro generates a requirements.md, a design.md, and a tasks.md automatically. You review and edit them. Then you click "implement" and the agent works through the task list sequentially, reading all three docs as context before each task.

It also runs "spec hooks" — automated checks that fire whenever you edit a file, verifying the implementation still aligns with the spec. Think of it as spec-to-code CI.

What makes Kiro different from Cursor or Claude Code isn't the AI model — it's the constraint. You're forced into the spec-first workflow. You can't just dump a vague prompt and watch it go.

GitHub Spec Kit

GitHub Spec Kit is a CLI that scaffolds the three-document structure and works with 22+ AI agent platforms: Claude Code, GitHub Copilot, Amazon Q, Gemini CLI, and more. It's lighter than Kiro — no new IDE — but it brings the same discipline to whatever toolchain you're already using.

The CLI generates a /specs directory, provides templates for requirements/design/tasks, and includes a workspace rule that tells your AI agent to read the specs before touching code.

My take: start with Spec Kit, move to Kiro if your team commits to it. Spec Kit costs nothing to adopt and you can introduce it one feature at a time. Kiro is a bigger surface area — new IDE, new workflow — and that's a real organizational change to ask of a team.

How to Write a Good Spec (The Part Everyone Skips)

The methodology is only as good as the specs you write. Bad specs produce AI code that's confidently wrong. Here's what actually matters:

Requirements: Write for the AI, not for yourself

The AI doesn't know your product. It doesn't know why you're building this feature, what failure looks like, or who the user is. Your requirements doc needs to answer all of that.

A good requirements doc includes:

The user story in the "As a [role], I want [action] so that [outcome]" format
Acceptance criteria as a numbered list — unambiguous, testable
What this feature explicitly does not do (scope boundaries)
The non-functional requirements: performance targets, security constraints, backward compatibility

A bad requirements doc is a paragraph that says "add user authentication." The AI will build something. It won't be what you wanted.

Design Doc: Make decisions explicit

The AI will make architecture decisions if you don't. And it will make them based on training data patterns, not your codebase context.

A good design doc includes:

The data model (schema or types) before the AI writes any
The component or module boundaries
Any decisions you already made and why
The explicit constraints: "we use Postgres, not SQLite," "the API must be backwards compatible with v1 clients"

A bad design doc is vague about how components interact. The AI fills in the blanks with whatever worked in its training data.

Task List: Atomic and ordered

Each task should be completable in one AI session. It should have a clear input (files to read, current state) and a clear output (what changes). The order matters — later tasks depend on earlier ones being done.

## Tasks

- [ ] 1. Create the `User` type in `src/types/user.ts`
- [ ] 2. Add `createUser` and `getUserById` to `src/db/users.ts`
- [ ] 3. Implement `POST /api/users` in `src/routes/users.ts` using the DB functions
- [ ] 4. Add input validation with Zod for the POST body
- [ ] 5. Write unit tests for `createUser` covering happy path and duplicate email

Not "implement user management." Five tasks with a clear sequence and no ambiguity about what "done" means.

What This Means for Product Managers

This is the part most SDD articles skip: the requirements and design docs aren't just for engineers. They're the most important thing a PM writes now.

In the old workflow, a PM writes a PRD, an engineer interprets it, builds something, and the gap between PRD and implementation is bridged by ten Slack messages, two sync meetings, and a lot of assumptions.

In SDD, the AI reads the requirements doc directly. The gap between "what the PM wanted" and "what was built" is now exactly as large as the gap between the PRD and the requirements doc. That's a gap the PM controls.

This means:

PMs who write precise requirements get features that match them
PMs who write vague requirements get AI-generated interpretations — fast
PMs who don't write specs at all get engineers who prompt the AI themselves, which produces... something

The discipline that SDD imposes on engineers also imposes on product. That's not a downside. It's the feature.

The Objection I Hear Most

"We don't have time to write specs. We need to move fast."

You're already writing specs. You're writing them in Slack messages, in Jira comments, in that "quick sync" at 3pm. You're just writing them in formats an AI can't read, after the code has already been written, in fragments spread across five tools.

SDD doesn't add work. It concentrates the work you're already doing into a form that's actually useful. Upfront clarity is cheaper than downstream rework. The teams shipping the most reliably right now aren't the ones who skip specs — they're the ones who've made spec-writing the fastest part of the process.

A good requirements doc takes 30 minutes. A design doc takes another 30. The task list takes 20. That's 80 minutes of up-front thinking that prevents two days of debugging AI-generated code that went sideways because the context was incomplete.

The Real Shift

Vibe coding was a proof of concept. It proved that AI could write code, that the velocity was real, that the tools had arrived. That was 2024.

2026 is about discipline. The teams winning right now are the ones who realized that AI coding tools are powerful exactly proportional to the quality of the context you give them. A great prompt gets you a great function. A great spec gets you a great system.

Spec-Driven Development is how you take the productivity gains from AI and make them compound across your whole team instead of being isolated in individual sessions. It's how you stop explaining your codebase to each other on every new sprint. It's how you let a junior write production-quality code because the spec contains all the decisions a senior would have made in their head.

The question isn't whether to adopt SDD. The question is whether you adopt it before or after the next rewrite.

Resources

Kiro IDE — AWS spec-driven IDE
GitHub Spec Kit — open source CLI for SDD
Martin Fowler on SDD tools: Kiro, spec-kit, and Tessl
Addy Osmani: How to write a good spec for AI agents
Thoughtworks: Spec-driven development unpacked
Anthropic: 2026 Agentic Coding Trends Report