What is a Spec? OpenSpec Tutorial and Spec Coding Guide

TL;DR: OpenSpec is a popular, tool-agnostic open-source framework for Spec Coding. Through its /opsx:propose → /opsx:apply → /opsx:archive three-step workflow, you have AI produce code under structured spec constraints rather than from a loose one-line prompt. This guide walks through the entire flow from installation to archival with a complete hands-on example.

Introduction

After understanding the theoretical foundation of Spec Coding, you might wonder: How does this actually work in a real IDE? What tools should I use to manage specification files?

The answer is OpenSpec — an open-source Spec Coding framework by Fission-AI (MIT license). It supports 20+ mainstream AI coding assistants and provides a complete artifact-driven development workflow.

What is OpenSpec?

OpenSpec is a lightweight spec layer that establishes an "agree before you build" contract between you and AI. Its core philosophy:

→ fluid not rigid
→ iterative not waterfall
→ easy not complex
→ built for brownfield not just greenfield
→ scalable from personal projects to enterprises

Every change generates a set of standardized artifacts:

5-Minute Setup

Prerequisites: Node.js 20.19.0 or higher.

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

cd your-project
openspec init

openspec init creates an openspec/ directory and AI guidance files at your project root. Once initialized, you can start using slash commands in your AI coding assistant immediately.

Also works with pnpm, yarn, bun, and nix. See the installation docs.

The Practical Trio: OpenSpec + CLAUDE.md + .cursorrules

In the 2026 AI programming ecosystem, these three form the complete Spec Coding toolchain:

1. OpenSpec: The artifact-driven development framework that manages the entire lifecycle of changes via slash commands.
2. CLAUDE.md: A project memory specification popularized by Anthropic. It acts as a "Project Constitution," recording core architecture, tech stack choices, and established conventions.
3. .cursorrules: IDE-level instructions that enforce code style and constraints (e.g., "Use TypeScript strict mode," "No inline styles").

The division of labor is clear: OpenSpec manages the workflow, CLAUDE.md manages memory, .cursorrules manages style.

Complete Walkthrough: Building "Recipe Search" with OpenSpec

Let's walk through OpenSpec's complete three-step workflow.

Step 1: /opsx:propose — Propose the Change

Don't just tell the AI "Write a search feature." Use OpenSpec's propose command:

/opsx:propose add-recipe-search

The AI automatically creates an openspec/changes/add-recipe-search/ directory with four artifacts:

openspec/changes/add-recipe-search/
├── proposal.md    ← Why we're building this feature
├── specs/         ← Requirements and acceptance scenarios
│   └── search-recipe.md
├── design.md      ← Technical approach
└── tasks.md       ← Implementation checklist

The specs/search-recipe.md will contain structured acceptance criteria:

## Context
Users need to search existing recipes by keyword and filter them by "Cooking Time."

## Acceptance Criteria (Scenarios)
#### Scenario 1: Basic Keyword Search
- **WHEN** the user enters "Egg"
- **THEN** the system should return a list of all recipes with "Egg" in the title

#### Scenario 2: Empty State Handling
- **WHEN** the search results are empty
- **THEN** the system should display "No recipes found" and recommend 3 popular recipes

## Constraints
- Search API response time must be < 200ms
- Search results must support pagination

The tasks.md generates an implementation checklist:

## Implementation Tasks
- [ ] 1.1 Create Search API Endpoint (`/api/recipes/search`)
- [ ] 1.2 Implement full-text search logic (using existing Prisma queries)
- [ ] 2.1 Implement Search UI components (SearchBar + ResultList)
- [ ] 2.2 Add "Cooking Time" filter
- [ ] 3.1 Write API-layer unit tests
- [ ] 3.2 Write component-level E2E tests

Your job at this point is: review these artifacts and ensure the AI understood your intent. You can modify any artifact at any time — OpenSpec's philosophy is "fluid not rigid," with no rigid phase gates.

Step 2: /opsx:apply — Execute Tasks

Once artifacts are reviewed, run the implementation command:

/opsx:apply

The AI executes tasks from tasks.md one by one. Output looks like:

Implementing tasks...
✓ 1.1 Create Search API Endpoint
✓ 1.2 Implement full-text search logic
✓ 2.1 Implement Search UI components
✓ 2.2 Add Cooking Time filter
✓ 3.1 Write API-layer unit tests
✓ 3.2 Write E2E tests
All tasks complete!

Key advantage: The AI reads only one task and its relevant spec context at a time. This "small-step" approach narrows the model's focus and reduces (though never eliminates) the chance of hallucination compared to throwing a vague requirement at it all at once. It does not replace review — you still read the diff and run the tests for each task before trusting the checkmark.

Step 3: /opsx:archive — Archive the Change

After all tasks pass tests:

/opsx:archive

OpenSpec archives the change to openspec/changes/archive/ with a timestamp:

openspec/changes/archive/2026-04-01-add-recipe-search/

This gives you a complete change history. Even three months later, you can quickly understand "why we did this" by reading the proposal.md.

Extended Workflow

The default profile ships a few more core commands beyond the three above: /opsx:explore (think through an idea before proposing) and /opsx:sync (synchronize artifact state). If you want the expanded profile, select it with openspec config profile and apply it with openspec update:

Command sets evolve. Run openspec update inside each project to regenerate AI guidance and ensure the latest slash commands are active, and check the OpenSpec commands doc for the current list.

OpenSpec vs. Alternatives

These three take different shapes rather than sitting on a single quality ladder. The snapshot below reflects mid-2026; all three move fast, so re-check the current docs before standardizing on one.

Note: Kiro is AWS's spec-driven IDE. It is not locked to a single model — through Amazon Bedrock it offers a choice of models (Claude, plus others). Treat "tool support" as a shape difference, not a ranking.

How to Write High-Quality Specs (The Golden Rules)

A good specification should have three key elements:

1. Use WHEN/THEN Syntax: This Behavior-Driven Development (BDD) syntax is extremely AI-friendly because it clarifies inputs and expected outputs.
2. Define Boundary Conditions: Tell the AI what to do if a user enters invalid characters, the network drops, or the data is empty.
3. Define the "Non-Goals": Explicitly forbid behaviors in the spec (e.g., "Do not modify the database schema," "Do not use third-party libraries").

Common Pitfalls: Avoiding Spec Coding Mistakes

• Over-specifying: OpenSpec's philosophy is "fluid not rigid." If you dictate every line of code, you lose the AI's flexibility. Specs should focus on "outcomes," not "low-level instructions."
• Ignoring the Single Source of Truth (SSOT): If you change requirements in chat but don't update the files in specs/, the AI will quickly become confused. Remember: If requirements change, update the Spec first.
• Lack of Task Verification: For every completed task, require the AI to run corresponding tests rather than just trusting its "I'm done" message.
• Skipping Archive: /opsx:archive is not optional. Archiving means knowledge persistence — three months later, you or your teammates can quickly understand the change history through archived artifacts.

Model Recommendations and Context Hygiene

OpenSpec works best with high-reasoning models. As of this writing the project README recommends Codex 5.5 and Opus 4.7 for both planning and implementation — but model names and version numbers change fast, and OpenSpec's own pages have carried slightly different figures at times, so verify against the current README before pinning a model.

Context hygiene: Before starting /opsx:apply, clear the AI's context window so it focuses on the current change's artifacts rather than stale conversation history.

Summary

Spec Coding is the dividing line between "toy projects" and "production-grade software." Through OpenSpec's three-step workflow (propose → apply → archive), you can turn AI into a true senior development partner rather than an error-prone intern.

Ready to go further? Learn how to build an automated runtime environment for your AI Agent with Harness Engineering.

Related Reading:

• Spec Coding Concept Complete Guide
• Vibe Coding Practical Guide: From Cursor to Claude Code
• Context Engineering: How to Provide the Perfect Context for AI