Spec-Driven Development with AI: Complete Guide (2026)

Beyond Vibe Coding

When Andrej Karpathy coined "vibe coding" in February 2025, he captured how most developers were using AI: conversationally, intuitively, accepting code that "felt right."

Five months later, AWS launched Kiro—an IDE built on the opposite philosophy. Where vibe coding is unstructured and exploratory, Kiro implements spec-driven development (SDD): a methodology where specifications come first, and code follows.

This guide covers everything you need to know about spec-driven development: the methodology, the workflow, the tools, and how to implement it in your organization.

What is Spec-Driven Development?

The Core Philosophy

Spec-driven development inverts the traditional AI coding workflow:

Vibe Coding	Spec-Driven Development
Describe → Generate → Test → Iterate	Specify → Review → Generate → Validate
AI makes design decisions	Humans make design decisions
Specs exist in chat history	Specs are versioned artifacts
Accept if it works	Accept if it meets spec

The key insight: specifications become executable artifacts. They're not just planning documents that get ignored—they drive implementation and validate results.

The Three Phases

Kiro's implementation of SDD breaks development into three distinct phases:

Phase 1: Requirements

Starting from natural language descriptions, generate:

• User stories: Who needs what, and why
• Acceptance criteria: Specific, testable conditions for completion
• Edge cases: Boundary conditions and error scenarios
• Dependencies: What this work requires or enables

These aren't rough notes—they're structured documents that the next phase consumes.

Phase 2: Design

With requirements in hand, generate technical design:

• Architecture diagrams: How components interact
• Data schemas: Database structures, API contracts
• Integration points: How this work connects to existing systems
• Technical constraints: Performance requirements, security considerations

Design documents are reviewed before any code is written. This is where humans maintain control over architecture.

Phase 3: Tasks

Design breaks down into implementation tasks:

• Ordered task list: Logical sequence of implementation steps
• Task-to-requirement mapping: Traceability from tasks to user stories
• Verification criteria: How to confirm each task is complete
• Estimated complexity: T-shirt sizing or story points

Only after all three phases are complete does code generation begin.

AWS Kiro: The Spec-Driven IDE

Overview

Kiro launched in public preview in July 2025 and reached general availability in November. It's built on Code OSS (VS Code's open-source base) with deep integration of spec-driven workflows.

Key facts:

• Not an "AWS service": Kiro is a standalone product, not part of AWS console
• No AWS account required: Works with any Amazon account (or no account during preview)
• Dual mode: Supports both "Vibe Mode" for exploration and "Spec Mode" for production
• Model choice: Claude Sonnet 4.0 and 3.7 available
• Free during preview: With usage limits

Core Features

Spec Mode Workflow

Kiro's spec mode guides you through the three-phase workflow with dedicated UI:

1. Requirements panel: Structured input for user stories and acceptance criteria
2. Design panel: Diagram generation and schema definition
3. Tasks panel: Ordered task list with progress tracking
4. Implementation: Code generation tied to active tasks

Each phase produces artifacts stored in your repository, creating a complete audit trail.

Agent Hooks

Agent Hooks are event-driven automations that run in the background:

• On save: Trigger AI to check for issues, generate tests, update docs
• On create: Automatically scaffold new files with boilerplate
• On delete: Clean up related files and references
• Manual triggers: Run specific agents on demand

Hooks are configured per-project and can chain multiple agents together. They're described as acting "like an experienced developer catching things you miss."

Steering Rules

Project-wide rules that guide AI behavior:

• Coding standards: Enforce style, naming conventions, patterns
• Security policies: Prevent generation of insecure code
• Architecture constraints: Keep AI aligned with system design
• Documentation requirements: Ensure generated code is properly documented

Steering rules are stored in your repository and applied to all AI interactions.

MCP Integration

Kiro supports the Model Context Protocol (MCP) for connecting external tools:

• Database access: Query schemas and data during generation
• API documentation: Reference external APIs accurately
• Internal tools: Connect to your organization's tooling
• Context providers: Add custom context sources

Autonomous Agent (Preview)

Kiro's autonomous agent, launching in preview, can:

• Work independently on complex tasks
• Maintain context across sessions
• Learn from project patterns
• Execute multi-step workflows

This represents the frontier of agentic development—AI that can handle entire feature implementations with minimal supervision.

Tool Comparison

When to Choose Each Tool

• AWS Kiro: Best for organizations committing to spec-driven development. Native workflow support, agent hooks, and enterprise features.
• Cursor: Best for teams wanting spec-driven principles with cutting-edge agentic features. Requires more manual discipline.
• Claude Code: Best for terminal-native developers who want to add structure through conventions and CLAUDE.md files.
• Windsurf: Best for exploration and rapid prototyping. Less suitable for production-grade spec-driven work.

Implementing Spec-Driven Development

For New Projects

1. Start with requirements, not code:
   • Write user stories before touching the IDE
   • Define acceptance criteria for each story
   • Review requirements with stakeholders
2. Create design documents:
   • Architecture diagrams for system structure
   • Data schemas for persistence layers
   • API contracts for integrations
3. Break down into tasks:
   • Order tasks by dependency
   • Map tasks to requirements
   • Define verification criteria
4. Generate and validate:
   • Generate code task-by-task
   • Validate against acceptance criteria
   • Review for spec compliance, not just functionality

For Existing Codebases

Spec-driven development excels at modernization:

1. Document the current state:
   • Generate specifications from existing code
   • Identify implicit requirements
   • Map current architecture
2. Define the target state:
   • What should the system look like after modernization?
   • What constraints must be preserved?
   • What behavior changes are acceptable?
3. Generate transformation:
   • AI generates migration code guided by specifications
   • Test against both current and target specs
   • Incremental migration with rollback capability

Delta Airlines used spec-driven approaches to modernize their development workflow, achieving 1,948% growth in AI tool adoption within six months. Product owners without coding experience could generate production-ready prototypes from specifications.

Team Adoption

1. Train on specification writing:
   • Writing good specs is a skill—different from prompting
   • Practice with low-stakes projects first
   • Review each other's specifications
2. Establish specification standards:
   • What does a "complete" requirement look like?
   • What design documents are required?
   • How are tasks structured?
3. Integrate with existing processes:
   • Spec review as part of PR process
   • Specifications in version control
   • Traceability from requirements to deployment

Best Practices

Specification Quality

• Be specific: "User can log in" is vague. "User can log in with email/password, receiving JWT token valid for 24 hours, with rate limiting of 5 attempts per minute" is actionable.
• Include constraints: Performance requirements, security constraints, compatibility needs—all belong in specs.
• Define edge cases: What happens when things go wrong? Specs should cover error scenarios.
• Version specifications: Specs change. Track changes with the same rigor as code.

Review Process

• Spec review before code review: Catch design issues before implementation
• Compliance verification: Does generated code meet the spec? This is the primary review criterion.
• Spec-code traceability: Every code change should trace to a spec change (or vice versa)

Tool Configuration

• Steering rules from day one: Establish coding standards before AI generates code
• Agent hooks for quality: Automate test generation, linting, documentation
• MCP connections: Give AI access to your architecture context

Conclusion

Spec-driven development represents the maturation of AI-assisted coding. Where vibe coding treats AI as an implementation partner that shares design authority, SDD keeps humans in control of design while delegating implementation.

The tools are ready. AWS Kiro provides native spec-driven workflows. Cursor and Claude Code can be adapted for structured work. The methodology is proven across enterprises from startups to Fortune 500.

The question isn't whether to adopt spec-driven development—it's how quickly you can establish the discipline before technical debt from unstructured AI coding becomes overwhelming.

---

For guidance on implementing spec-driven development in your organization, schedule a consultation.

Frequently Asked Questions

Frequently Asked Questions