Spec-Driven Development: How Kiro and AI Agents Build From Specs

Summary

Spec-driven development emerged because vibe coding hit a wall. Typing "build me an auth system" into Claude or Copilot works for demos. It does not work for systems that need to handle edge cases, satisfy compliance requirements, or survive a code review. The fix is not better models. It is better inputs.

What Is Spec-Driven Development

Spec-driven development treats specifications as first-class artifacts. Instead of writing code and documenting it later, you write a detailed spec first, then use AI agents to generate an implementation that satisfies the spec. The spec becomes the source of truth. Code is the output.

The arxiv paper "Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants" (February 2026) organizes SDD into three levels of rigor:

Most teams operate at level 1. The tools are pushing everyone toward level 2. Level 3 remains experimental.

Why Vibe Coding Breaks Past 500 Lines

Vibe coding works when the entire system fits in a single prompt. A landing page. A CLI script. A data pipeline with one input and one output. Past roughly 500 lines, three failure modes emerge consistently:

The Kiro team at AWS built their entire product around this observation. As one developer wrote after switching to spec-driven workflows: "Most of the time, I was not fixing bugs. I was fixing unclear decisions I never made explicitly."

Specs solve all three problems. Implicit requirements become explicit acceptance criteria. Context pollution shrinks because the agent reads the spec instead of the entire codebase. Drift stops because every session checks against the same contract.

The Three-Phase Workflow

Every major SDD tool converges on the same three phases, with minor naming differences. Kiro calls them Requirements, Design, Tasks. GitHub Spec Kit calls them Specify, Plan, Tasks. The structure is the same.

Phase 1: Requirements

Define what the system should do in behavioral terms. Not "use PostgreSQL" but "as an admin, I can query user activity for the last 90 days and receive results in under 2 seconds." Kiro uses EARS notation (Easy Approach to Requirements Syntax) for acceptance criteria. GitHub Spec Kit uses a freeform spec.md.

# Feature: Organization Registration

## User Story
As an entity owner, I want to register my organization
so that employees can access the platform under a shared account.

## Acceptance Criteria
- GIVEN a valid business email, WHEN the owner submits registration,
  THEN a new organization is created with the owner as admin
- GIVEN an email domain already registered, WHEN the owner submits,
  THEN the system rejects with "Domain already in use"
- GIVEN registration succeeds, THEN a verification email is sent
  within 30 seconds
- GIVEN no verification within 72 hours, THEN the organization
  is soft-deleted

## Out of Scope
- SSO configuration (separate spec)
- Billing setup (handled by onboarding flow)
- Custom domain mapping

Phase 2: Design

Translate requirements into technical architecture. Data schemas, API endpoints, sequence diagrams, error handling strategy. The agent generates this from Phase 1, but you review and edit it. This is where bad architectural decisions get caught before they become 2,000 lines of code.

## Data Model

Organization {
  id: UUID (primary key)
  name: string (3-100 chars)
  domain: string (unique, validated)
  owner_id: UUID (references users.id)
  status: enum [pending_verification, active, suspended, deleted]
  created_at: timestamp
  verified_at: timestamp | null
}

## API Endpoints

POST /api/organizations
  - Body: { name, domain, owner_email }
  - Returns: 201 with organization object
  - Errors: 409 if domain exists, 422 if validation fails

## Sequence: Registration Flow

Owner -> API: POST /api/organizations
API -> DB: Check domain uniqueness
API -> DB: Insert organization (status: pending_verification)
API -> Email Service: Send verification link
API -> Owner: 201 Created

Phase 3: Tasks

Break the design into discrete, trackable implementation steps. Each task maps back to an acceptance criterion. Each task is small enough for an agent to complete in one session without context pollution.

## Tasks

- [x] Task 1: Create Organization database migration
  - Add organizations table with all fields from design.md
  - Add unique index on domain column
  - Linked to: Acceptance Criteria 1

- [x] Task 2: Implement POST /api/organizations endpoint
  - Validate input, check domain uniqueness, insert record
  - Return 409 for duplicate domains, 422 for invalid input
  - Linked to: Acceptance Criteria 1, 2

- [ ] Task 3: Email verification service
  - Send verification link with signed token
  - Token expires after 72 hours
  - Linked to: Acceptance Criteria 3

- [ ] Task 4: Soft-delete cron job
  - Run every hour, delete unverified orgs older than 72h
  - Linked to: Acceptance Criteria 4

Spec-Driven Development Tools Compared

Three tools dominate the SDD space in March 2026. They target different levels of rigor and different workflows.

Kiro

AWS's bet on spec-driven development. A VS Code fork that makes specs the default workflow, not an afterthought. The three-phase process (requirements.md, design.md, tasks.md) is enforced by the IDE. Agent hooks trigger automated actions on file events, so the agent can auto-update specs when code changes.

The limitation: Kiro applies the same three-phase process to everything, including bug fixes. Martin Fowler's team called it a "sledgehammer for a nut" on small problems. Also locked to the Kiro IDE, which means your spec workflow cannot follow you to Cursor or Claude Code.

GitHub Spec Kit

The open-source alternative. 71,000 GitHub stars, 2,300+ forks, MIT license. Works with 20+ agents through slash commands (/specify, /plan, /tasks). Uses a constitution.md file for immutable project principles, similar to how CLAUDE.md works.

The limitation: verbose. The Marmelab team tested Spec Kit on a simple date-display feature and got 8 files and 1,300+ lines of spec text. The Martin Fowler team noted that reviewing the generated markdown was more tedious than reviewing code directly. The overhead pays off on large features but is disproportionate for small changes.

CLAUDE.md and Rules Files

The lightweight option. A single markdown file at the repo root that tells the agent how to behave: coding conventions, architecture constraints, testing requirements. Not a full SDD workflow, but it captures the most important benefit (explicit constraints) with minimal overhead.

CLAUDE.md for Claude Code, .cursorrules for Cursor, copilot-instructions.md for GitHub Copilot. Same concept, different filenames. These files are spec-first at level 1: they guide the agent but do not enforce a multi-phase workflow.

SDD vs TDD vs BDD

Spec-driven development does not replace test-driven development. It operates at a different layer. Understanding where each practice fits prevents the "is this just waterfall?" confusion.

The practical relationship: SDD generates the design that BDD features validate, which TDD tests implement. A spec says "registration must verify email within 30 seconds." A BDD feature file turns that into a Gherkin scenario. A TDD test validates the email service returns within 30 seconds.

You do not need all three. Most teams using SDD with AI agents skip BDD entirely because the spec already captures behavior. TDD remains valuable for unit-level correctness that specs do not cover.

When SDD Works (and When It Does Not)

The Marmelab critique crystallizes the risk: SDD can become "systematic bureaucracy" if applied uniformly. Their test showed a simple date feature generating 1,300+ lines of spec. The fix is not abandoning specs but calibrating rigor to task size. A CLAUDE.md file for small tasks. A full Kiro workflow for features that will live in production for years.

How to Start with Spec-Driven Development

Do not adopt all three levels at once. Start at level 1 (spec-first) and move to level 2 (spec-anchored) only when you have evidence it helps.

Week 1: Add a CLAUDE.md (or equivalent)

Create a markdown file at your repo root that tells your AI agent the project's constraints: tech stack, coding conventions, testing requirements, architecture rules. This takes 15 minutes and immediately reduces agent drift.

# Project: Acme Dashboard

## Stack
- Next.js 15, TypeScript strict, Tailwind CSS
- PostgreSQL with Drizzle ORM
- Auth: Clerk

## Rules
- Server components by default. Client components only for interactivity.
- All database access through Drizzle ORM, never raw SQL.
- Every API route must validate input with Zod.
- No console.log in production code. Use structured logging.

## Testing
- Unit tests: Vitest
- E2E tests: Playwright
- Run `bun test` before committing.

## Architecture
- /app/(auth)/ routes require Clerk middleware
- /app/api/ routes return JSON, never HTML
- Shared types in /types/, never co-located

Week 2-3: Try Spec Kit on One Feature

Pick a feature that is clearly defined and will take more than a day to implement. Run through the Specify, Plan, Tasks cycle. Measure: did the spec catch design errors before coding? Did the agent stay closer to plan?

Week 4+: Evaluate and Calibrate

If the overhead paid off, expand to more features. If it felt like busywork, drop back to CLAUDE.md and only use full specs for features over 1,000 lines. The right level of SDD depends on team size, feature complexity, and how often requirements change.

The Implementation Gap: Specs Are Only Half the Problem

A good spec tells the agent what to build. It does not guarantee the agent builds it well. The Martin Fowler team observed that "despite comprehensive workflows and larger context windows, agents frequently ignore instructions or over-interpret them, creating duplicates or diverging from specifications."

This is the implementation gap. Specs reduce the problem space from "anything the agent can imagine" to "what the spec defines." But within that reduced space, the agent still needs to produce correct, efficient code. Two bottlenecks remain:

This is where the underlying model infrastructure matters. Spec-driven agents still need fast, accurate code edits to translate specs into working code. A spec that takes 3 phases to write and 45 seconds to implement is productive. A spec that takes 3 phases to write and 10 minutes of hallucinated edits to implement is not.

FAQ