OpenSpec Workflow Guide: Spec-Driven AI Development in Claude Code
Discover how OpenSpec structures AI agent workflows in Claude Code, key validation pitfalls to avoid, and when spec-driven development fits your existing codebase.
AI coding agents are increasingly integrated into modern software engineering, but unguided agent execution often leads to uncoordinated code changes. Spec-Driven Development (SDD) via tools like OpenSpec has seen rapid adoption, growing from 81,000 monthly npm downloads in January 2026 to approximately 2.9 million by October 2026. With roughly 72,000 GitHub stars, the MIT-licensed Fission-AI project provides a command-line interface and toolset designed to force coding agents to write structured plans before editing code.
How OpenSpec structures agent workflows
OpenSpec operates by generating four core planning artifacts alongside an existing project: a proposal explaining why a change is needed, a spec delta outlining post-change requirements, a design note covering technical implementation, and a task list tracking action items. Built for existing codebases rather than greenfield builds, OpenSpec requires Node.js 20.19 or newer and defines changes as deltas categorized under ADDED, MODIFIED, REMOVED, or RENAMED requirements.
In environments like Claude Code, the development loop relies on three primary slash commands: /opsx:propose to create the planning artifacts, /opsx:apply to implement tasks in a clean chat context, and /opsx:archive to merge the deltas into permanent standing specifications. Legacy slash commands, such as /openspec:proposal, alongside auto-generated files like CLAUDE.md, were completely retired during the January 2026 1.0.0 release. In recent versions like 1.14.3, configurations are managed in openspec/config.yaml, where project constraints and artifact length rules can be set manually.
Human oversight and syntax validation
While OpenSpec includes automated checks via openspec validate --strict and diff inspections via openspec show --diff, manual review during the proposal phase remains indispensable. Requirements in spec deltas rely on strict keyword syntax using terms like SHALL or MUST, while individual scenarios require four-level markdown headings (#### Scenario:).
A subtle structural syntax error can bypass validation. If a scenario header uses three hashtags (### Scenario:) instead of four, the validator does not fail with an error. Instead, it outputs an easily overlooked INFO line and drops the scenario from validation. If other valid scenarios exist within that requirement block, the change is marked valid, leaving the agent to execute code without enforcing the dropped business rule.
Developers must verify scenario counts against original feature requirements before running /opsx:apply. When managing diverse AI workflows, developers can try top AI models cheaply through one API at https://apixoai.online to compare how different model backends handle plan generation and code implementation.
What it means for developers
Adopting OpenSpec introduces useful structure for maintainable software, but teams must navigate specific trade-offs:
- Managing document overhead: Creating four Markdown files for every code change introduces non-trivial ceremony. OpenSpec is recommended for medium to large modifications on established apps. Minor single-file edits or simple copy tweaks should bypass the tool entirely.
- Preventing specification drift: An academic survey of spec-driven tools published in June 2026 identified spec drift and missing standardized benchmarks as ongoing industry challenges. Running
/opsx:archiveto update standing specifications is only valuable if developers actually consult those specs later. - Selecting the right methodology: OpenSpec is designed specifically for code that already exists by updating living documentation over time. For massive prospective features requiring detailed product modeling before writing code, alternative tools like the BMad Method (version 6.12.4) use persona-driven workflows involving simulated product managers and system architects.
Source: OpenSpec Tutorial (2026): Spec-Driven Development in Claude Code, Step by Step — Towards AI. Written by the Apixo team from that report.
One key for Claude, GPT, GLM, DeepSeek and more. Pay per token with crypto.
Get your API key
