TL;DR

This OpenSpec tutorial teaches you how to implement Spec-Driven Development (SDD) in your daily workflow. By mastering three simple slash commands (/opsx:propose, /opsx:apply, /opsx:archive), you can shift from unpredictable AI chats to structured, highly reliable AI engineering, reducing hallucinations and making your codebase maintainable.

📋 Table of Contents

✨ Key Takeaways

  • Structured Workflow: OpenSpec transforms AI coding from ad-hoc chats into a rigorous, spec-driven pipeline.
  • Three-Command Mastery: The entire lifecycle is managed via /opsx:propose, /opsx:apply, and /opsx:archive.
  • Zero Hallucinations: By breaking down tasks and restricting context to specific spec files, AI hallucination rates drop significantly.
  • Universal Compatibility: Works seamlessly with Cursor, Windsurf, Trae, and Claude Code.

💡 Quick Tool: Use our free Markdown Editor to write and preview your spec.md files online before feeding them to your AI assistant.

What is Spec-Driven Development (SDD)?

Spec-Driven Development (SDD) is an AI-native programming paradigm where the specification document is the primary artifact, and the code is entirely derived from it. Instead of chatting endlessly with an AI, developers define system behaviors and constraints in a structured document, and the AI agent implements the logic within those exact boundaries.

In traditional development, specs often become outdated as soon as coding begins. In SDD, the spec is the Single Source of Truth (SSOT). If requirements change, you update the spec first, not the code.

📝 Glossary: Prompt Engineering — SDD is essentially the highest form of system-level prompt engineering for AI coding assistants.

How OpenSpec Works

OpenSpec is the leading open-source framework for SDD created by Fission-AI. It provides a lightweight, directory-based structure that AI agents can easily parse and execute.

The core philosophy of OpenSpec is fluid not rigid. It doesn't force you into heavy enterprise UML diagrams; instead, it uses simple markdown files with BDD (Behavior-Driven Development) syntax like WHEN/THEN.

graph LR A["1. /opsx:propose"] -->|Generates Spec| B["specs/ & tasks.md"] B -->|Review| C["2. /opsx:apply"] C -->|Executes Code| D["Code Changes"] D -->|Tests Pass| E["3. /opsx:archive"] style A fill:#e1f5fe,stroke:#01579b style C fill:#fff3e0,stroke:#e65100 style E fill:#e8f5e9,stroke:#2e7d32

The Three Pillars of OpenSpec

Command SDD Phase Purpose
/opsx:propose Definition Creates the proposal.md, specs/, and tasks.md artifacts.
/opsx:apply Execution Tells the AI to read tasks.md and implement the code step-by-step.
/opsx:archive Persistence Moves the completed spec into the archive for historical memory.

OpenSpec Tutorial: Step-by-Step Guide

Let's dive into the practical part of this OpenSpec tutorial. We will build a simple "JSON Validator" feature using SDD principles.

Step 1: Installation and Initialization

First, install OpenSpec globally and initialize it in your project.

bash 
# Install OpenSpec globally
npm install -g @fission-ai/openspec@latest

# Navigate to your project and initialize
cd my-ai-project
openspec init

This creates an openspec/ directory in your root folder, establishing the scaffolding needed for the AI to understand your SDD workflow.

Step 2: Propose a Change

In your AI IDE (like Cursor or Trae), open the chat and use the propose command.

Your Input:

text 
/opsx:propose add-json-validator-feature

The AI will generate several files under openspec/changes/add-json-validator-feature/:

  • proposal.md: The high-level goal.
  • specs/spec.md: The detailed requirements using WHEN/THEN.
  • tasks.md: The step-by-step implementation checklist.

Review the specs/spec.md: Make sure the AI captured your intent. A good spec looks like this:

markdown 
### Requirement: JSON Validation Logic

#### Scenario: Valid JSON Input
- **WHEN** the user inputs `{"key": "value"}` and clicks Validate
- **THEN** the system shows a success message
- **AND** formats the JSON with 2-space indentation

#### Scenario: Invalid JSON Input
- **WHEN** the user inputs `{"key": "value"` (missing brace)
- **THEN** the system catches the SyntaxError
- **AND** displays exactly which line the error occurred on

Step 3: Apply the Tasks

Once you are happy with the spec and tasks, instruct the AI to execute.

Your Input:

text 
/opsx:apply add-json-validator-feature

The AI will now read tasks.md, implement the code, and check off the tasks one by one. By forcing the AI to follow the task list, you prevent it from randomly modifying unrelated files—a common issue in Vibe Coding.

Step 4: Archive the Artifacts

After the code is written and tests pass, you must archive the change. This is critical for long-term project memory.

Your Input:

text 
/opsx:archive add-json-validator-feature

The AI will move the folder to openspec/changes/archive/[date]-add-json-validator-feature/. Future AI sessions can read this archive to understand why certain architectural decisions were made.

🔧 Try it now: While building data-intensive apps, use our free JSON Formatter to validate your test payloads instantly.

Advanced OpenSpec Techniques

1. Combining OpenSpec with CLAUDE.md

OpenSpec handles the lifecycle of a specific feature, while CLAUDE.md handles the global rules of the repository.

For the best SDD development experience, define your global constraints in CLAUDE.md:

markdown 
# Project Constitution
- We use React Functional Components only.
- We never use inline CSS; use CSS Modules.
- All new features MUST be developed using OpenSpec `/opsx:propose`.

2. Handling Task Deviations

If the AI encounters an unexpected issue during /opsx:apply (e.g., a library is deprecated), do not just tell it to hack a fix. Stop the apply process, manually update specs/spec.md and tasks.md to reflect the new reality, and then resume /opsx:apply. This ensures your SSOT remains accurate.

Best Practices for SDD Development

  1. Keep Specs Fluid, Not Rigid — Focus on the what and why (boundary conditions, error handling), not the exact code syntax.
  2. Atomic Proposals — Do not propose "Build an entire e-commerce backend" in one go. Propose "add-user-auth", then "add-product-catalog".
  3. Mandatory Archiving — Never skip /opsx:archive. Unarchived changes clutter the active workspace and confuse the AI's context window.
  4. Use High-Reasoning Models — For the propose phase, always use models with strong reasoning capabilities like Claude 3.5 Sonnet or GPT-4o.

⚠️ Common Mistakes:

  • Changing requirements mid-flight → If you change your mind, update the spec.md first. Don't just chat with the AI to change the code.
  • Skipping the review phase → Always read the tasks.md generated by /opsx:propose before running /opsx:apply.

FAQ

Q1: How do I use OpenSpec in an existing project?

You can introduce OpenSpec gradually. Run openspec init in your existing repo. For your next small feature or bug fix, use /opsx:propose. You don't need to write specs for legacy code; just use SDD for all new changes moving forward.

Q2: Does SDD development slow down coding?

In the first 10 minutes, yes, because you are reviewing specs instead of watching code generate. However, over a 2-week sprint, SDD drastically reduces debugging time, regressions, and "AI hallucination loops", ultimately making your team much faster.

Q3: OpenSpec vs. Cursor Rules: What is the difference?

Cursor Rules (.cursorrules) dictate how the AI writes code (e.g., syntax, style). OpenSpec dictates what the AI builds and manages the workflow. They are highly complementary; you should use both together.

Q4: Can I use OpenSpec without an AI IDE?

Technically yes, you can manually write the spec.md and tasks.md files and then use a CLI tool to execute them, but the true magic happens when you integrate OpenSpec commands directly into an AI assistant's chat interface.

Summary

Mastering Spec-Driven Development (SDD) with OpenSpec is the key to scaling AI engineering in 2026. By adopting the /opsx:propose → /opsx:apply → /opsx:archive workflow, you transform chaotic AI chats into a predictable, highly reliable software factory.

Embrace the SDD paradigm today, and stop fighting AI hallucinations!

👉 Start using Markdown Editor now — Perfect for drafting your OpenSpec proposals offline.