Spec-Driven Development

A comprehensive guide comparing different approaches to spec-driven development when working with AI coding assistants like Claude Code, GitHub Copilot, Cursor, and others.

🎯 What is Spec-Driven Development?

Spec-driven development is the practice of writing specifications before writing code—or asking an AI tool to write code. Instead of coding first and documenting later, you start with a spec that acts as a contract for how your code should behave.

The Problem Without Specs

When working with AI coding assistants without specifications:

❌ Context loss - AI forgets previous decisions
❌ Inconsistent outputs - Different results each time
❌ Scope creep - AI adds unwanted features
❌ Rework cycles - Constant corrections and revisions
❌ Misalignment - AI misunderstands requirements

The Benefits With Specs

With proper specifications:

✅ Predictable results - Consistent AI outputs
✅ Clear expectations - Humans and AI aligned
✅ Faster iteration - Less back-and-forth
✅ Better quality - AI stays on track
✅ Maintainability - Clear documentation from day one

📊 Comparison Overview

Approach	Type	Cost	Complexity	Best For
BMAD-METHOD	Framework	Free (OSS)	High	Large teams, enterprise projects
OpenSpec	CLI Tool	Free (OSS)	Low	Any project size, version control
GitHub Spec Kit	CLI Toolkit	Free (OSS)	Medium	GitHub users, structured workflow
Kiro.dev	IDE Platform	Paid	Medium	Individual devs, startups
CodeGuide.dev	Documentation	Free	Low	Documentation-focused projects
No Spec (Traditional)	Ad-hoc	Free	Low	Small scripts, prototypes

🔍 Detailed Comparison

1. BMAD-METHOD™

BMAD-METHOD on GitHub Universal AI Agent Framework for software development

What It Is

BMAD (Breakthrough Method of Agile AI-Driven Development) is a comprehensive AI agent framework that uses a two-phase approach: Agentic Planning followed by Context-Engineered Development.

Key Features

Agentic Planning

Dedicated AI agents (Analyst, PM, Architect) collaborate to create detailed requirements and architecture documents

Context Engineering

Scrum Master agent transforms plans into hyper-detailed development stories with full context embedded

Multi-Domain

Expansion packs for creative writing, business strategy, wellness, education beyond just coding

Customizable

Build custom AI agents for specialized fields and workflows

How It Works

Analyst Agent → PM Agent → Architect Agent → Scrum Master → Developer
   (Research)   (Requirements)  (Architecture)   (Stories)    (Implementation)

Pros & Cons

Pros ✅	Cons ❌
Comprehensive framework - Covers entire development lifecycle	Steep learning curve - Complex setup and methodology
Eliminates context loss - Full context in every story	Heavy tooling - Requires Node.js v20+, web UI, IDE integration
Team collaboration - Multiple AI agents work together	Overhead for small projects - Overkill for simple tasks
Enterprise-ready - Designed for large, complex projects	Team coordination - Best with dedicated team members
Extensible - Supports custom agents and domains

Best For

Large enterprise projects
Teams with dedicated roles (PM, Architect, Developer)
Complex multi-phase projects
Organizations building multiple AI-driven products

Installation

Clone the Repository

git clone https://github.com/bmad-code-org/BMAD-METHOD.git
cd BMAD-METHOD

Install Dependencies
Terminal window
```
bun install
```
Start the Web UI
Terminal window
```
bun run dev
```
Open in Browser Visit http://localhost:3000 to access the BMAD planning interface

Project Directory Structure

Directoryyour-project/
- Directorybmad/
  - Directoryrequirements/
    analyst-research.md
    pm-requirements.md
  - Directoryarchitecture/
    system-design.md
    tech-decisions.md
  - Directorystories/
    story-001.md
    story-002.md
  - Directoryagents/
    custom-agent-config.json
- Directorysrc/
  - (your source code)
- Directory.bmad/
  - config.json

2. OpenSpec

OpenSpec on GitHub Spec-driven development CLI tool for AI coding assistants

What It Is

OpenSpec is a lightweight CLI tool that implements spec-driven development with a simple two-folder model: current specs and proposed changes. It integrates seamlessly with existing AI coding tools.

Key Features

Two-Folder Model

specs/ for current truth, changes/ for proposed updates

Change Management

Draft, review, implement, and archive changes with clear audit trail

Universal Integration

Works with Claude Code, Cursor, Copilot, and any AI coding tool

No API Keys

Fully local, no external dependencies or accounts required

How It Works

Directoryopenspec/
- Directoryspecs/
  - feature-a.md
  - feature-b.md
- Directorychanges/
  - add-feature-c.md
  - update-feature-a.md

Pros & Cons

Pros ✅	Cons ❌
Simple and lightweight - Minimal setup, just folders and markdown	Manual process - Requires discipline to follow workflow
Version control friendly - Works perfectly with Git	No GUI - Command-line only
Tool agnostic - Compatible with any AI coding assistant	Limited automation - No automatic spec generation
Clear audit trail - Every change is tracked and reviewable	No multi-agent - Single developer focused
No dependencies - No API keys or external services

Best For

Solo developers and small teams
Projects already using Git
Teams using multiple AI coding tools
Projects requiring clear change history

Install Globally
Terminal window
```
bun add -g @fission-ai/openspec
```
Navigate to Your Project
Terminal window
```
cd your-project
```
Initialize OpenSpec
Terminal window
```
openspec init
```
Verify Setup Check that openspec/ folder was created with specs/ and changes/ subdirectories

Install Globally

npm install -g @fission-ai/openspec@latest

Navigate to Your Project
Terminal window
```
cd your-project
```
Initialize OpenSpec
Terminal window
```
openspec init
```
Verify Setup Check that openspec/ folder was created with specs/ and changes/ subdirectories

Project Directory Structure

Directoryyour-project/
- Directoryopenspec/
  - Directoryspecs/
    feature-authentication.md
    feature-dashboard.md
    api-endpoints.md
  - Directorychanges/
    add-payment-feature.md
    update-auth-flow.md
  - Directoryarchived/
    completed-change-001.md
- Directorysrc/
  - (your source code)
- Directory.openspec/
  - config.json

3. GitHub Spec Kit

GitHub Spec Kit Official GitHub toolkit for spec-driven development with AI coding agents

What It Is

GitHub Spec Kit is an official toolkit from GitHub that streamlines software development through a structured spec-driven approach with AI assistance. It treats specifications as executable guides rather than disposable planning documents.

Key Features

Slash Commands

Built-in commands like /speckit.specify, /speckit.plan, /speckit.tasks for structured workflow

Multi-Agent Support

Works with Claude, GitHub Copilot, Gemini, Cursor, and other AI coding agents

Intent-Driven

Focus on “what” and “why” before determining technical implementation

Executable Specs

Specifications become living guides for development, not throwaway documents

How It Works

Constitution → Specify → Plan → Tasks → Implement
  (Project setup) (Requirements) (Architecture) (Breakdown) (Code)

Pros & Cons

Pros ✅	Cons ❌
Official GitHub tool - Backed by GitHub’s expertise	Relatively new - Smaller community compared to alternatives
Slash command workflow - Simple, intuitive commands	Command-line focused - No GUI interface
Multi-agent compatible - Works with any AI coding tool	Python dependency - Requires Python/uv installation
Structured process - Clear phases from spec to implementation	Learning curve - Need to understand the workflow phases
Technology agnostic - Start with intent, not tech stack

Best For

Developers using GitHub and AI coding agents
Teams wanting official GitHub-backed tools
Projects requiring structured spec-to-code workflow
Organizations adopting spec-driven practices

Installation

Install uv (Python package manager)
- macOS/Linux
- Windows
Terminal window
curl -LsSf https://astral.sh/uv/install.sh | sh
Terminal window
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Spec Kit

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Initialize a Project
Terminal window
```
specify init my-project
```
Or Initialize in Existing Directory
Terminal window
```
specify init . --ai claude
```

Project Directory Structure

Directoryyour-project/
- Directory.speckit/
  - constitution.md
  - Directoryspecifications/
    feature-001-spec.md
    feature-002-spec.md
  - Directoryplans/
    architecture-plan.md
    implementation-plan.md
  - Directorytasks/
    task-breakdown.md
  - config.json
- Directorysrc/
  - (your source code)
- README.md

4. Kiro.dev

Kiro.dev IDE AI-powered IDE with built-in spec-driven development

What It Is

Kiro is an AI-powered Integrated Development Environment designed specifically for spec-driven development. It transforms prompts into structured requirements, system design, and implementation tasks.

Key Features

Spec-to-Code

Automatically turns prompts into requirements, design, and discrete tasks

Autonomous Hooks

Trigger tasks on events (file save) - generate docs, tests, optimize code

Auto Mode

Mixed frontier models for autonomous complex feature development

Multi-Modal

Support for design images, screenshots, and other inputs

How It Works

User Prompt → Requirements → System Design → Implementation Tasks → Code

Pros & Cons

Pros ✅	Cons ❌
All-in-one IDE - Complete development environment	Paid service - Not free (pricing varies)
Automatic spec generation - AI creates specs from prompts	Platform lock-in - Proprietary IDE, not tool-agnostic
Autonomous agents - Background tasks for docs, tests, optimization	Learning curve - New IDE to learn
Multi-language - Python, JavaScript, TypeScript, and more	Cloud dependency - Requires internet connection
Import VS Code settings - Easy migration from existing setup

Best For

Individual developers
Startups building MVPs quickly
Teams wanting integrated spec-driven workflow
Developers comfortable with new IDEs

Installation

Visit Kiro.dev Go to kiro.dev
Sign Up Create an account (GitHub sign-in available)
Import Settings (Optional) Import your VS Code settings for faster setup
Start Your First Project Click “New Project” and start with a prompt

Project Directory Structure

Directoryyour-project/
- Directory.kiro/
  - Directoryspecs/
    feature-001-spec.md
    feature-002-spec.md
  - Directoryrequirements/
    user-requirements.md
  - Directorydesign/
    system-architecture.md
    component-breakdown.md
  - Directorytasks/
    implementation-tasks.json
  - settings.json
- Directorysrc/
  - (your source code generated by Kiro)
- Directorytests/
  - (auto-generated tests)
- Directorydocs/
  - (auto-generated documentation)

5. CodeGuide.dev

CodeGuide.dev Documentation generator for AI coding projects

What It Is

CodeGuide focuses on creating detailed documentation for AI coding projects. It helps maintain comprehensive project documentation that serves as specifications for AI assistants.

Key Features

Documentation Focus

Generate and maintain detailed project documentation

AI-Friendly

Documentation formatted for AI assistant consumption

Living Docs

Keep documentation in sync with codebase

How It Works

CodeGuide emphasizes documentation as the specification layer, ensuring that:

All features have clear documentation
Documentation is accessible to AI assistants
Changes update documentation automatically

Pros & Cons

Pros ✅	Cons ❌
Documentation first - Ensures comprehensive project docs	Limited scope - Primarily documentation, not full workflow
AI-optimized - Format works well with AI assistants	Manual maintenance - Requires keeping docs updated
Lightweight - Minimal overhead	Less structure - Not as formal as other approaches
Integration friendly - Works with existing tools

Best For

Documentation-focused teams
Projects requiring extensive API docs
Teams using various AI coding tools
Maintaining legacy projects

Installation

Visit codeguide.dev for documentation best practices.

Project Directory Structure

Directoryyour-project/
- Directorydocs/
  - README.md
  - ARCHITECTURE.md
  - API.md
  - Directoryfeatures/
    authentication.md
    dashboard.md
    api-endpoints.md
  - Directoryguides/
    setup.md
    deployment.md
  - CHANGELOG.md
- Directorysrc/
  - (your source code)
- Directory.codeguide/
  - Directorytemplates/
    …
  - config.json

6. Traditional Approach (No Spec)

What It Is

The traditional ad-hoc approach where you directly prompt AI assistants without formal specifications or documentation.

How It Works

Prompt → Code → Test → Debug → Iterate

Pros & Cons

Pros ✅	Cons ❌
Quick start - No setup required	Context loss - AI forgets previous decisions
Flexible - Change direction easily	Inconsistent - Different results each time
Simple - No methodology to learn	Scaling issues - Breaks down on large projects
Fast for prototypes - Great for quick experiments	Maintainability - Hard to onboard new team members
	No audit trail - Unclear why decisions were made

Best For

Quick prototypes and experiments
Learning and exploring new technologies
Very small scripts (< 100 lines)
Throwaway code

Project Directory Structure

Directoryyour-project/
- Directorysrc/
  - index.js
  - utils.js
  - (unstructured code files)
- package.json
- README.md
- (no formal specs or documentation)

🎯 Decision Matrix

Choose the right approach for your needs:

Choose BMAD-METHOD if you:

✅ Working on enterprise-scale projects
✅ Have dedicated team roles (PM, Architect, etc.)
✅ Need comprehensive planning phase
✅ Want multi-agent collaboration
✅ Building multiple related products

Ideal Team Size: 3-10+ members

📊 Feature Comparison

Feature	BMAD	OpenSpec	GitHub Spec Kit	Kiro	CodeGuide	No Spec
Learning Curve	High	Low	Medium	Medium	Low	None
Setup Time	Hours	Minutes	10-15 mins	Minutes	Minutes	None
Cost	Free	Free	Free	Paid	Free	Free
Team Size	3-10+	1-5	1-10	1-3	Any	1
Multi-Agent	✅ Yes	❌ No	✅ Yes	✅ Yes	❌ No	❌ No
Version Control	✅ Yes	✅ Yes	✅ Yes	⚠️ Limited	✅ Yes	⚠️ Manual
Auto Spec Gen	✅ Yes	❌ No	⚠️ Guided	✅ Yes	⚠️ Partial	❌ No
IDE Integration	✅ Yes	⚠️ Manual	⚠️ Manual	✅ Built-in	⚠️ Manual	N/A
Change Tracking	✅ Yes	✅ Yes	✅ Yes	✅ Yes	⚠️ Manual	❌ No
Documentation	✅ Auto	📝 Manual	✅ Structured	✅ Auto	✅ Focus	❌ None
Tool Agnostic	❌ No	✅ Yes	✅ Yes	❌ No	✅ Yes	✅ Yes
Offline Support	✅ Yes	✅ Yes	✅ Yes	❌ No	✅ Yes	✅ Yes

🚀 Getting Started Guide

Step 1: Assess Your Needs

Recommended: OpenSpec or Kiro

If you’re working alone:

OpenSpec - If you want free, simple, git-integrated
Kiro - If you want automated specs and don’t mind paying

Step 2: Implement

Install your chosen tool Follow the installation instructions for your selected approach
Create your first spec Start small with one feature or module
Test with AI assistant Prompt your AI tool referencing the spec
Iterate and refine Improve your spec format based on results
Scale up Expand to more features as you get comfortable

💡 Best Practices

BMAD-Specific Tips

Invest time in the planning phase
Let AI agents collaborate, don’t rush them
Review agent outputs before proceeding
Customize agents for your domain

OpenSpec-Specific Tips

Create templates for common change types
Use meaningful file names in changes/
Archive promptly after implementation
Commit specs with related code changes

Kiro-Specific Tips

Start with clear, detailed prompts
Use Auto mode for complex features
Leverage autonomous hooks for repetitive tasks
Import VS Code settings for faster onboarding

CodeGuide-Specific Tips

Document as you go, not after
Include examples in documentation
Keep API docs comprehensive
Link code to relevant documentation

📈 Real-World Examples

Example 1: Building a Dashboard (OpenSpec)

# Add Analytics Dashboard

## Requirements
- Display key metrics: users, revenue, engagement
- Real-time updates via WebSocket
- Responsive design (mobile + desktop)
- Export data to CSV

## Technical Design
- React + Recharts for visualization
- TanStack Query for data fetching
- Cloudflare Workers for backend
- ClickHouse for analytics data

## Implementation Tasks
1. Create dashboard layout component
2. Build metric cards with Recharts
3. Implement WebSocket connection
4. Add CSV export functionality
5. Write unit tests for calculations

## Acceptance Criteria
- [ ] Dashboard loads in < 2 seconds
- [ ] Real-time updates every 5 seconds
- [ ] Mobile responsive (320px+)
- [ ] CSV export includes all visible data

Example 2: API Endpoint (BMAD)

After Agentic Planning, Scrum Master generates:

# Story: Create User Registration Endpoint

## Context
Part of the Authentication System (see architect-doc-001.md)
Implements requirements from PM-REQ-003.md

## Full Implementation Details
- Endpoint: POST /api/auth/register
- Validation: Email, password (8+ chars, 1 uppercase, 1 number)
- Database: Users table (see schema.sql)
- Security: bcrypt hash (cost 10), rate limit (5/min per IP)
- Response: JWT token (expires 24h)

## Error Handling
- 400: Invalid input (specific field errors)
- 409: Email already exists
- 429: Rate limit exceeded
- 500: Server error

## Testing
- Unit tests for validation logic
- Integration tests for full flow
- Load test: 100 concurrent registrations

## Dependencies
- bcrypt: ^5.1.0
- jsonwebtoken: ^9.0.0
- express-rate-limit: ^6.0.0

Example 3: Feature Spec (Kiro Auto Mode)

Prompt to Kiro:

“Create a real-time collaborative whiteboard with drawing tools, shapes, text, and multi-user cursors”

Kiro generates:

Requirements document
System architecture
Component breakdown
API specification
Implementation tasks

Then Auto mode implements everything autonomously.

🔗 Resources

Official Documentation

BMAD-METHOD Docs Comprehensive guide to BMAD framework

OpenSpec GitHub OpenSpec tool and documentation

Kiro.dev Platform Sign up and start building with Kiro

GitHub Spec Kit GitHub's official spec-driven toolkit

Community & Tutorials

🎯 Conclusion

Spec-driven development is becoming essential for effective AI-assisted coding. The right approach depends on your:

Project size - Solo vs team vs enterprise
Budget - Free vs paid tools
Workflow - Existing tools vs new platform
Complexity - Simple scripts vs complex systems
Team structure - Dedicated roles vs generalists

Quick Recommendations

Scenario	Best Choice	Why
Solo dev, small project	OpenSpec	Simple, free, git-friendly
Solo dev, complex project	Kiro.dev	Automated specs, powerful features
GitHub user, structured workflow	GitHub Spec Kit	Official tool, slash commands, multi-agent
Small team	OpenSpec	Easy collaboration via Git
Large enterprise	BMAD-METHOD	Multi-agent, comprehensive planning
Documentation focus	CodeGuide.dev	Docs as specs
Quick prototype	No Spec	Speed over structure

Last updated: October 2025