OpenSpec — Spec-Driven Development for AI Coding Agents

Overview

OpenSpec is an open-source, MIT-licensed framework from Fission AI for Spec-Driven Development (SDD) with AI coding assistants. With over 62,000 GitHub stars, it has rapidly become one of the most popular approaches to structuring AI-assisted software development.

SDD flips the traditional coding workflow: instead of asking an AI agent to write code directly, OpenSpec requires a specification to be written and validated first. The AI agent then generates code that must conform to the spec, with automated verification ensuring the implementation matches the intent. This approach reduces hallucination, improves code quality, and makes AI-generated code auditable.

Available at github.com/Fission-AI/OpenSpec.

Features

• Spec-First Workflow: Write and validate a specification before any code generation
• Automated Spec Verification: AI-generated code is checked against the spec automatically
• AI Coding Agent Integration: Works with Claude Code, Cursor, GitHub Copilot, and other AI coding tools
• Open-Source and MIT Licensed: Free to use and extend without vendor lock-in
• Spec Language: Declarative format for defining behavior, constraints, and acceptance criteria
• Regression Testing: Specs double as living documentation and regression test suites
• Team Collaboration: Specs serve as a shared contract between human and AI collaborators
• Version Control for Specs: Specs are tracked alongside code in Git for full auditability

Installation

# Install as a global tool
npm install -g @fission-ai/openspec

# Or use with npx
npx @fission-ai/openspec init

# Or install as a dev dependency
npm install --save-dev @fission-ai/openspec

Quick Start

# Initialize a new OpenSpec project
npx @fission-ai/openspec init

# Write a spec (YAML or Markdown)
# .openspec/example.yaml

# example.yaml
name: user-authentication
description: |
  Implement a REST API endpoint that authenticates users
  via email and password, returning a JWT token.
acceptance-criteria:
  - Returns 200 with JWT token on valid credentials
  - Returns 401 on invalid credentials
  - Hashes passwords with bcrypt before comparison
constraints:
  - Must use Express.js
  - Must validate input with Zod

# Generate code from the spec
npx @fission-ai/openspec generate example.yaml

# Verify the generated code against the spec
npx @fission-ai/openspec verify example.yaml

Core Concepts

Specification-First

Every development task starts with a spec. The spec is a declarative document describing what the code should do, how it should behave, and what constraints apply. This forces clarity before implementation.

Agent-Guided Generation

AI coding agents consume the spec and generate code that satisfies it. The agent's output is then verified against the spec automatically, catching deviations before they reach production.

Living Documentation

Specs are version-controlled alongside code, serving as always-up-to-date documentation. As code evolves, specs evolve with it, ensuring documentation never drifts.

Examples

REST API Specification

name: todo-api
description: A REST API for managing todos
endpoints:
  - path: /todos
    method: GET
    response: "Array of todo objects with id, title, completed, createdAt"
  - path: /todos
    method: POST
    requestBody: "{ title: string, completed?: boolean }"
    response: "Created todo object with 201 status"

Security-Constrained Feature

name: admin-panel
description: Admin-only dashboard for system metrics
access:
  roles: [admin]
  auth: required
constraints:
  - Must implement rate limiting
  - Must sanitize all SQL queries

Pros

• ✅ Reduces AI agent hallucination and off-spec code generation
• ✅ Improves code quality through spec verification
• ✅ Specs serve as living, version-controlled documentation
• ✅ Integrates with existing AI coding tools
• ✅ Strong community with 62K+ stars
• ✅ MIT licensed and open-source

Cons

• ❌ Extra step in the development workflow (spec before code)
• ❌ Requires discipline to write quality specs
• ❌ Verification may not catch all logical errors
• ❌ Newer framework with evolving best practices
• ❌ Spec language may need learning for complex systems

When to Use

• AI-Assisted Development: Any project using AI coding agents (Claude Code, Cursor, Copilot)
• Quality-Critical Systems: Projects where code correctness is paramount
• Team Projects: Where specs serve as contracts between team members and AI
• Auditable Codebases: Projects requiring clear documentation of what code should do
• Regression Prevention: Teams struggling with AI-generated regressions

Resources

• GitHub Repository
• OpenSpec Documentation
• Fission AI