Spec-Driven Development Methodology

A systematic approach to software development that prioritizes planning, documentation, and structured workflows before writing code.

The Core Principle

Spec First, Code Second

Every feature starts with a specification that defines what to build, why it's needed, how it will work, and when it's complete.

This isn't just about writing better requirements - it's a complete methodology that includes:

  • Slash commands for streamlined workflows ( /spec:create , /spec:implement , /spec:review )
  • Output styles that transform Claude's behavior
  • TodoWrite integration for task tracking
  • CLI tools for project management ( ck init , ck doctor , ck hook )
  • Hook system for custom automation

The Workflow

1️⃣ Requirements

What and Why. Define clear, testable requirements using EARS notation. Every requirement follows the pattern: 

WHEN [condition/event] THE SYSTEM SHALL [expected behavior]

2️⃣ Design

How. Plan the architecture, data models, component structure, and testing strategy. The design phase answers how requirements will be implemented.

3️⃣ Tasks

Steps. Break down the design into specific, actionable implementation tasks. Each task has clear acceptance criteria and dependencies.

4️⃣ Implementation

Build. Code systematically, task by task, with test-driven development and TodoWrite tracking. Verify acceptance criteria before marking complete.

EARS Notation

EARS (Easy Approach to Requirements Syntax) provides a structured format for writing clear, testable requirements.

The Format

WHEN [trigger/condition] THE SYSTEM SHALL [specific behavior]

Examples

# User Input Validation
WHEN a user submits a form with invalid email
THE SYSTEM SHALL display validation error below the email field

# Success Flow
WHEN a user clicks "Save" with all required fields filled
THE SYSTEM SHALL save data to database and show success message

# Error Handling
WHEN database connection fails
THE SYSTEM SHALL retry up to 3 times with exponential backoff

Why EARS?

  • Unambiguous - Clear conditions and expected behaviors
  • Testable - Each requirement becomes a test case
  • Complete - Forces consideration of all scenarios
  • Maintainable - Easy to update as requirements change

Benefits Over Ad-Hoc Development

🐛 Fewer Bugs

Planning catches edge cases and architectural issues before coding. Test-driven implementation ensures requirements are met.

⚡ Faster Iteration

Changes to specs are faster than refactoring code. Get stakeholder approval before investing in implementation.

📚 Better Documentation

Specs become living documentation. Future developers understand what was built, why, and how.

✅ Clearer Success Criteria

Know exactly when a feature is "done". Acceptance criteria prevent scope creep.

🔄 Evolvable System

Specs can evolve and supersede each other. Track how features change over time.

🤝 Better Collaboration

Specs provide a shared language. Claude and developers work from the same source of truth.

More Than Just Hooks

Claude Kiro is a complete methodology , not just a collection of hooks. It provides:

Slash Commands

/spec:create guides you through requirements → design → tasks with approval gates. /spec:implement loads context and tracks progress. /spec:review validates completeness and quality.

Output Style Transformation

The spec-driven output style changes how Claude behaves - emphasizing planning, systematic workflows, and test-driven development across all interactions.

CLI Tooling

ck init sets up your project. ck doctor validates configuration. ck hook manages custom automation.

TodoWrite Integration

Task tracking is built into the workflow. Claude maintains a todo list synchronized with spec tasks.

Philosophical Foundation

Claude Kiro implements the spec-driven methodology from Kiro.dev , adapted for Claude Code workflows.

The methodology is based on principles from:

  • Test-Driven Development (TDD) - Write tests first, implement to pass
  • Domain-Driven Design (DDD) - Model software around business concepts
  • Documentation as Code - Keep docs close to implementation
  • Agile Principles - Iterative development with quick feedback
Learn More: Visit Kiro.dev to dive deeper into the methodology philosophy and advanced patterns.

Next Steps

Now that you understand the methodology:

Learn Slash Commands See Examples