What is Spec-Driven Development?#

Spec-Driven Development (SDD) is an approach where you write structured specifications before writing code with AI assistance. Think of it as “documentation-first” development. The specification becomes a contract between you and the AI—a shared source of truth that describes what needs to be built, why it matters, and how it should behave.

At its core, SDD addresses a fundamental challenge in AI-assisted coding: alignment. Without a spec, you’re asking an AI to read your mind. With a spec, you’re providing a blueprint that both you and the AI can reference, refine, and validate against.

As the SDD philosophy states:

“In this new world, maintaining software means evolving specifications. The lingua franca of development moves to a higher level, and code is the last-mile approach.”

What Makes a Good Spec?#

A spec in SDD is not just a lengthy document—it’s a structured, behavior-oriented artifact written in natural language. Good specs:

• Describe intent, not implementation: They focus on what the system should do and why, not how it should be coded
• Use structured formats: Gherkin-style scenarios (GIVEN/WHEN/THEN), user stories (As a… I want… So that…), and acceptance criteria
• Are reviewable: They can be read, understood, and approved before code generation begins
• Capture requirements: They document the problem space clearly enough that multiple developers (or AI agents) could implement them consistently

Example spec format:

1
### Feature: User Authentication
2

3
**User Story:**
4
As a registered user, I want to log in with my email and password
5
so that I can access my personalized dashboard.
6

7
**Acceptance Criteria:**
8
- GIVEN a user with valid credentials
9
  WHEN they submit the login form
10
  THEN they receive an authentication token
11
  AND are redirected to the dashboard
12

13
- GIVEN a user with invalid credentials
14
  WHEN they submit the login form
15
  THEN they see an error message
16
  AND the login attempt is logged for security review

The Three Levels of SDD#

SDD exists on a spectrum of implementation maturity:

SDD vs Traditional Approaches#

SDD isn’t waterfall reborn—it’s an iterative, fluid approach. You don’t write a complete specification for an entire application upfront. Instead, you write specs for individual features or changes, implement them, and then move to the next spec.

Why SDD Matters in the AI Coding Era#

AI coding assistants are powerful but unpredictable when requirements live only in chat history or the developer’s head. SDD adds a lightweight spec layer that ensures:

1. Agreement before building: Human and AI align on specs before code gets written
2. Reduced hallucinations: Clear constraints and acceptance criteria guide the AI
3. Reviewable intent: Code reviewers can understand what was supposed to happen, not just what was coded
4. Maintainable knowledge: Specs capture the “why” behind decisions, persisting beyond the current chat session

What is OpenSpec?#

OpenSpec is a lightweight, open-source framework that implements Spec-Driven Development principles. Created by Fission AI, it’s designed to bring structure to AI-assisted coding without the ceremony of heavyweight tools.

Key characteristics:

• Universal: Works with 20+ AI coding assistants (Claude Code, Cursor, Codex, GitHub Copilot, Opencode, and more)
• Open source: MIT licensed, community-driven
• No lock-in: No API keys required, no proprietary formats, no MCP dependencies
• Lightweight: Minimal setup, intuitive commands, organized folder structure

OpenSpec’s philosophy:

1
→ fluid not rigid
2
→ iterative not waterfall
3
→ easy not complex
4
→ built for brownfield not just greenfield
5
→ scalable from personal projects to enterprises

How OpenSpec Implements SDD#

OpenSpec organizes each change into a dedicated folder with structured artifacts:

1
openspec/
2
└── changes/
3
    └── your-feature-name/
4
        ├── proposal.md      # Why we're doing this, what's changing
5
        ├── specs/           # Requirements and scenarios
6
        ├── design.md        # Technical approach
7
        └── tasks.md         # Implementation checklist

The OpenSpec workflow mirrors SDD principles:

1. Propose (/opsx:propose): Create a proposal and spec for a change
2. Apply (/opsx:apply): Implement the tasks defined in the spec
3. Archive (/opsx:archive): Preserve the spec when complete

Spec deltas: OpenSpec captures changes to requirements as “spec deltas”—diffs that show how intent has evolved. This makes it easy for developers to understand how they’re modifying the system at a high level, without diving into implementation details.

OpenSpec vs Alternatives#

vs GitHub Spec-kit:

• Spec-kit is thorough but heavyweight, with rigid phase gates and extensive markdown files
• OpenSpec is lighter and lets you iterate freely between phases
• Spec-kit requires Python setup; OpenSpec is Node.js-based and simpler to install

vs Kiro:

• Kiro is powerful but locks you into their VS Code distribution and Claude models
• OpenSpec works with the tools you already use and supports multiple AI assistants
• Kiro has a prescribed workflow; OpenSpec offers both simple and expanded workflows

vs Nothing (raw AI coding):

• Without specs, you’re relying on chat history and vague prompts
• OpenSpec brings predictability and structure without adding bureaucracy

While OpenSpec works with many tools, I personally prefer using it with Opencode because of its terminal-based approach, which aligns well with OpenSpec’s lightweight philosophy. The combination gives you speed, flexibility, and structure without IDE lock-in.

Installation & Setup#

Requirements:

• Node.js 20.19.0 or higher
• npm, pnpm, yarn, or bun

Installation:

1
# Install OpenSpec globally
2
npm install -g @fission-ai/openspec@latest
3

4
# Verify installation
5
openspec --version

Initialize in your project:

1
cd your-project-directory
2
openspec init

This creates the .openspec/ directory structure and configures your AI assistant with the necessary slash commands.

Your First Spec: The Propose Workflow#

The simplest way to use OpenSpec is the three-step propose workflow:

Step 1: Create a proposal

Tell your AI assistant:

1
/opsx:propose "add dark mode support to the application"

OpenSpec will create a folder at openspec/changes/add-dark-mode/ containing:

• proposal.md: Explains why dark mode is needed, the scope, and success criteria
• specs/: Directory with requirement files
  • Functional requirements (what dark mode should do)
  • Scenarios (GIVEN/WHEN/THEN acceptance criteria)
  • Edge cases and constraints
• design.md: Technical approach, component changes, state management strategy
• tasks.md: Checklist of implementation steps with tracking

Step 2: Review the artifacts

Read through the generated files. Do they capture your intent? Are the requirements clear? This is your chance to refine the spec before implementation begins.

You can edit any of these files directly—the spec is yours to shape.

Step 3: Apply the spec

Once you’re satisfied with the proposal:

1
/opsx:apply

Your AI assistant will:

1. Read the tasks.md checklist
2. Implement each task in order
3. Mark tasks as complete
4. Report progress

You can review each change as it’s made, request adjustments, or refine the spec mid-implementation.

Step 4: Archive when complete

When all tasks are done:

1
/opsx:archive

This moves the spec to openspec/changes/archive/ with a timestamp, preserving it for future reference while keeping your workspace clean for the next feature.

Simple Workflow: Propose → Apply → Archive#

Best for: Bug fixes, small features, tweaks, experiments

This is the workflow described above. It’s lightweight and fast—perfect when you don’t need extensive planning.

Example:

1
You: /opsx:propose "fix the login error message"
2
AI:  Created openspec/changes/fix-login-error/
3
     ✓ proposal.md — clarify error message requirements
4
     ✓ specs/ — scenarios for different error cases
5
     ✓ tasks.md — 2 implementation tasks
6

7
You: /opsx:apply
8
AI:  ✓ Task 1.1: Update error message in auth middleware
9
     ✓ Task 1.2: Add client-side error display
10
     All tasks complete!
11

12
You: /opsx:archive
13
AI:  Archived to openspec/changes/archive/2026-04-04-fix-login-error/

Expanded Workflow: Full SDD Lifecycle#

Best for: Large features, architectural changes, team collaboration

For more complex work, OpenSpec offers an expanded workflow with additional phases:

Commands:

• /opsx:new "feature-name" — Create a new spec with full artifacts
• /opsx:continue — Resume work on an existing spec
• /opsx:ff — Fast-forward through phases (skip to implementation)
• /opsx:verify — Check current implementation against the spec
• /opsx:sync — Sync specs with current code state (for brownfield)
• /opsx:bulk-archive — Archive multiple completed specs
• /opsx:onboard — Analyze existing codebase to create initial specs

Example expanded workflow:

1
You: /opsx:new "implement user dashboard"
2
AI:  Created openspec/changes/implement-user-dashboard/
3
     ✓ proposal.md — Dashboard overview and goals
4
     ✓ specs/
5
       - functional-requirements.md
6
       - user-scenarios.md
7
       - data-requirements.md
8
     ✓ design.md — Component architecture, API contracts
9
     ✓ tasks.md — 15 implementation tasks organized by phase
10

11
You: [Review and refine artifacts]
12

13
You: /opsx:continue
14
AI:  Resuming from design phase.
15
     Would you like to refine design or proceed to implementation?
16

17
You: proceed to implementation
18
AI:  Beginning implementation phase...
19

20
You: /opsx:verify
21
AI:  Verification complete:
22
     ✓ 12 of 15 tasks complete
23
     ⚠ Task 3.2: Chart component missing accessibility labels
24
     ⚠ Task 4.1: API pagination not implemented
25
     Would you like to address these gaps?
26

27
You: /opsx:apply
28
AI:  ✓ Task 3.2: Added ARIA labels to chart
29
     ✓ Task 4.1: Implemented cursor-based pagination
30
     All tasks complete!
31

32
You: /opsx:archive
33
AI:  Archived to openspec/changes/archive/...

Workflow Selection Guide#

Use Simple Workflow when:

• The change is small (1-3 files modified)
• You’re working alone
• The requirement is straightforward
• You need to move fast

Use Expanded Workflow when:

• The change affects multiple components or systems
• You’re working with a team
• The requirement needs clarification or has dependencies
• You want detailed tracking and verification

The key principle: Start simple. If you find yourself wishing you had more structure, switch to the expanded workflow. OpenSpec is fluid— you’re never locked into a rigid process.

Why They Work Well Together#

While OpenSpec supports 20+ AI assistants, I find that OpenSpec + Opencode is a particularly powerful combination:

Terminal-native workflow:

• Opencode runs in your terminal, which aligns with OpenSpec’s file-based approach
• You can navigate openspec/ folders using standard shell commands
• No IDE lock-in or context switching

Context hygiene:

• Opencode benefits from clean, structured context—and that’s exactly what OpenSpec provides
• Each spec is self-contained in its folder, making it easy to load relevant context
• Spec deltas help you understand changes without polluting the conversation

Speed and flexibility:

• Both tools prioritize speed over ceremony
• Quick iteration on specs, then quick implementation
• Easy to switch between “planning mode” (editing specs) and “coding mode” (implementation)

Brownfield-friendly:

• Opencode excels at exploring existing codebases
• OpenSpec’s /opsx:onboard and /opsx:sync work well with Opencode’s codebase analysis
• Together, they help you bring structure to legacy projects gradually

Practical Integration Patterns#

Pattern 1: Clean Context Approach

Before starting a new feature, clear your Opencode context and start fresh:

1
/clear          # Clear Opencode context
2
/opsx:propose "add user profile page"
3
[Review spec]
4
/opsx:apply     # Implementation with clean context

Benefit: The AI isn’t influenced by previous conversations or unrelated code.

Pattern 2: Spec-First Exploration

Use Opencode to explore the codebase, then create a spec based on what you learn:

1
Show me how authentication works in this project
2
[Opencode explains the auth system]
3

4
/opsx:propose "extend auth system to support OAuth"
5
[Spec incorporates Opencode's findings]

Pattern 3: Iterative Refinement

Refine specs with Opencode before implementation:

1
/opsx:propose "optimize database queries"
2

3
[Opencode reviews proposal.md]
4
"The spec suggests indexing the users table, but we already have a composite index.
5
Let's refine the spec to focus on the orders table instead."
6

7
[Edit spec with Opencode's input]
8

9
/opsx:apply

Pattern 4: Parallel Workflows

Work on multiple specs simultaneously:

1
Terminal 1: /opsx:propose "feature-a"  → review phase
2
Terminal 2: /opsx:apply "feature-b"    → implementation phase
3
Terminal 3: /opsx:archive "feature-c"  → completion phase

Benefit: While one feature is being reviewed, another can be implemented.

Example: Building a Feature with OpenSpec + Opencode#

Here’s a high-level walkthrough of a real workflow:

The Goal: Add a “remember me” feature to the authentication system

Step 1: Explore with Opencode

1
How is session management currently implemented?
2
[Opencode shows current session middleware and cookie handling]

Step 2: Create the spec

1
/opsx:propose "add remember me functionality to login"

Opencode generates:

• proposal.md: Overview of “remember me” functionality
• specs/session-extension.md: Requirements for extended sessions
• design.md: Changes to auth middleware and cookie configuration
• tasks.md: 6 implementation tasks

Step 3: Review and refine You read through the spec and realize it doesn’t address security concerns:

1
The spec looks good, but we need to add a requirement:
2
"Extended sessions should only work on the same device/browser"

Opencode updates the spec.

Step 4: Implement

1
/opsx:apply

Opencode works through the tasks:

• Adds “remember me” checkbox to login form
• Modifies session middleware to support extended duration
• Updates cookie settings for persistent storage
• Adds device fingerprinting for security

Step 5: Verify

1
/opsx:verify

Opencode confirms all acceptance criteria are met and security requirements are satisfied.

Step 6: Archive

1
/opsx:archive

The spec is preserved for future reference—if someone asks “why do we fingerprint devices?” the answer is in the archived spec.

When to Use SDD/OpenSpec#

✅ Good fit for SDD:

• Medium-to-large features (affects multiple files or components)
• Features with complex business logic or edge cases
• Team projects where specs serve as documentation
• Brownfield development (extending existing systems)
• API contracts and integrations
• Security-sensitive features (authentication, authorization, payments)

❌ Overkill for SDD:

• One-line fixes (typos, config tweaks)
• Trivial changes (renaming a variable)
• Rapid prototyping and experimentation (“vibe coding”)
• Spikes and proofs-of-concept
• Changes you’re going to throw away

Decision framework:

• Will this feature need maintenance or iteration? → Use SDD
• Are there multiple ways to implement this? → Use SDD
• Will someone else need to understand this later? → Use SDD
• Is this a one-time, throwaway experiment? → Skip SDD

Writing Good Specs#

Do:

• Start with the “why”—what problem are you solving?
• Use specific acceptance criteria (GIVEN/WHEN/THEN)
• Include edge cases and error scenarios
• Keep specs focused (one feature per spec)
• Iterate on specs before implementation
• Write for a human reader, not just the AI

Don’t:

• Over-specify implementation details (let the AI figure out the “how”)
• Write specs for trivial changes
• Make specs so long they’re tedious to review
• Treat specs as static—update them as requirements evolve
• Confuse functional requirements with technical constraints

Example of good vs. bad spec writing:

❌ Bad: “Implement a good login system”

✅ Good:

1
Feature: Secure User Login
2

3
User Story:
4
As a registered user, I want to log in securely
5
so that only I can access my account.
6

7
Acceptance Criteria:
8
- GIVEN valid credentials
9
  WHEN submitted
10
  THEN user is authenticated and receives a JWT
11
  AND a secure HTTP-only cookie is set
12

13
- GIVEN invalid credentials
14
  WHEN submitted
15
  THEN user sees a generic error message
16
  AND the failed attempt is logged
17

18
- GIVEN 5 consecutive failed attempts
19
  WHEN the 6th attempt is made
20
  THEN the account is temporarily locked
21
  AND the user receives an email notification

Common Pitfalls to Avoid#

1. The Sledgehammer Problem

Don’t use SDD for trivial changes. If you’re fixing a typo or changing a color, writing a full spec is overkill. Use your judgment—SDD should save time, not create bureaucracy.

2. Skipping Review

The power of SDD is in reviewing specs before implementation. Don’t rush to /opsx:apply without reading the generated artifacts. The spec is your chance to catch misalignment early.

3. Static Spec Syndrome

Specs should evolve. If you discover a new requirement during implementation, update the spec. The spec should always reflect the current understanding of what needs to be built.

4. Confusing Functional and Technical Specs

• Functional specs describe what the system should do (requirements, behavior)
• Technical specs describe how it should be implemented (architecture, libraries)

SDD works best when specs are primarily functional. Technical details can be in the design.md, but the core requirements should be implementation-agnostic.

5. Perfectionism

Specs don’t need to be perfect— they need to be good enough to guide implementation. If you find yourself endlessly refining a spec, you might be in analysis paralysis. Iterate during implementation instead.

Context Hygiene Tips#

When using OpenSpec with AI assistants like Opencode:

• Clear context before major specs: Start with a clean slate for complex features
• Reference specs explicitly: Point the AI to specific files: “See openspec/changes/auth/specs/security.md”
• Use spec deltas for changes: When updating requirements, show the diff: “We’re changing the session timeout from 24h to 7d for ‘remember me’ users”
• Archive promptly: Don’t leave completed specs in the changes/ folder—archive them to maintain clarity

Conclusion#

Spec-Driven Development isn’t a return to waterfall—it’s an evolution of agile practices for the AI coding era. By establishing clear specifications before implementation, you:

• Align human and AI intent before code is written
• Review requirements rather than just code
• Capture knowledge that persists beyond chat sessions
• Build predictability into AI-assisted development

OpenSpec makes SDD accessible. It’s lightweight enough for personal projects, structured enough for team collaboration, and flexible enough to adapt to your workflow. Whether you’re using Claude Code, Cursor, GitHub Copilot, or my personal favorite, Opencode, OpenSpec provides the scaffolding for better AI-assisted development.

Your next step: Try /opsx:propose on your next feature. Start simple—don’t overthink it. Write a spec, review it, implement it, and see how it feels. SDD is a skill that improves with practice, and OpenSpec lowers the barrier to getting started.

The future of AI-assisted coding isn’t about replacing human judgment—it’s about augmenting it. Specs are how we communicate our judgment to AI systems. Start writing specs, and start building better software.