OpenSpec is a spec-driven development toolkit for existing codebases. It locks requirements into Markdown artifacts first, then lets AI execute against those artifacts to reduce context poisoning, attention drift, and implementation distortion. It works well with environments such as Claude Code, Cursor, and Aider. Keywords: OpenSpec, Spec-Driven Development, AI Coding.
Technical Specification Snapshot
| Parameter | Description |
|---|---|
| Project Name | OpenSpec |
| Core Positioning | Spec-Driven Development (SDD) for existing codebases |
| Language/Runtime | Node.js 20.19.0+ |
| Interaction Model | CLI + AI IDE slash commands |
| Compatible Tools | Claude Code, Cursor, Copilot, Aider |
| Collaboration Protocol | Markdown spec documents + file-system artifact flow |
| Core Dependency | @fission-ai/openspec |
| Documentation Layout | specs/, changes/, archive/, config.yaml |
| Typical Scenarios | Brownfield incremental development, bug fixes, refactoring and migration |
| Repository | github.com/fission-ai/openspec |
OpenSpec fixes the loss of control in AI coding for complex engineering with a spec-first model
In large codebases, the most common problem with AI-generated code is not that the model cannot write code. The problem is that it gradually drifts away from the target. Context poisoning causes the model to treat noise as signal, and attention drift makes long conversations slowly diverge from the original requirement. OpenSpec addresses this by solidifying requirements, design, and tasks into Markdown artifacts ahead of time, so AI always starts from reviewable specifications.
At its core, OpenSpec is not just another code generator. It is a layer of specification management. Compared with Spec Kit, which is better suited to greenfield projects, OpenSpec focuses more on incremental evolution in existing codebases. Its documentation is lighter, its workflow is more flexible, and its token consumption is lower.
AI Visual Insight: The image shows a technical article cover centered on OpenSpec, with the core message focused on “spec-driven development.” Visually, it emphasizes capturing specifications before coding, then moving into design and implementation. This suggests a workflow centered on document artifacts rather than on real-time conversation.
OpenSpec is better suited to brownfield projects for a reason
Spec Kit tends to use linear gating, which works well for building new systems from scratch. OpenSpec uses dependency-driven workflows and change isolation, making it a better fit for incremental iteration in established enterprise systems. For business-critical code that requires long-term maintenance, this model is easier to adopt in practice.
# Install OpenSpec
npm install -g @fission-ai/openspec@latest
# Initialize it in an existing project
cd your-project
openspec initThis command sequence installs OpenSpec locally and injects the spec workflow into an existing project.
OpenSpec uses four directory types to define the current system state, intended changes, and historical records
After initialization, the project gets a new openspec/ directory. This is not a conventional documentation repository. It acts as the control plane for AI collaboration. Inside it, specs/ records the system’s current behavior, changes/ records features or fixes in progress, and archive/ preserves the historical trail.
The directory structure is the foundation for recoverability, traceability, and collaboration in OpenSpec
openspec/
├── specs/ # Primary specs: the source of truth for current system behavior
├── changes/ # Active changes: what this iteration is going to modify
├── archive/ # Historical archive: completed changes
└── config.yaml # Project context and rulesThis structure defines how OpenSpec manages current state, target changes, and history as separate concerns.
Each change usually contains four kinds of artifacts: proposal.md, specs/, design.md, and tasks.md. Together, they answer four questions: why this change exists, what it changes, how it should be designed, and how it should be executed. Note that this is an enabling relationship, not a rigid gate. Teams can revise or supplement artifacts according to their actual pace.
proposal.md -> specs/ -> design.md -> tasks.mdThis dependency chain describes the input relationship between artifacts, making it easier for AI to generate downstream content from upstream documents.
Project context configuration has a major impact on the quality of every downstream artifact
Many teams run only openspec init and overlook config.yaml. In practice, this file defines OpenSpec’s quality ceiling. The reason is simple: context is injected into every artifact generation process, which makes it a write-once, reuse-everywhere mechanism.
Configuring context reduces repetitive prompting and improves generation consistency
schema: spec-driven
context: |
## Project Overview
The XXX system is responsible for task scheduling and execution engine submission
## Tech Stack
Java / Spring Boot / Redis / MySQL
## Coding Standards
APIs must remain backward compatible
rules:
proposal:
- Proposals must include background, goals, and a solution overview
tasks:
- Each task should be independently testableThis configuration injects project facts into AI, reducing the cost of repeatedly explaining the tech stack and constraints.
OpenSpec command coverage spans the full lifecycle of exploration, planning, implementation, verification, and archiving
OpenSpec provides a fast mode by default, which works well for small features with clear requirements. A typical path is /opsx:propose -> /opsx:apply -> /opsx:archive. If you switch to extended mode, you get finer-grained commands such as new, continue, ff, verify, and sync.
Different commands map to different reasoning stages, not just feature groups
When requirements are still ambiguous, start with /opsx:explore. When requirements are clear and you want to move quickly, use /opsx:propose or new + ff. When you need to recover from an interruption, simply rerun /opsx:apply <change-name>.
# Enable extended mode
openspec config profile
openspec update
# View active changes
openspec listThese commands switch the workflow mode and show the status of current parallel changes.
In real teams, OpenSpec delivers the most value through change isolation and interruption recovery
OpenSpec packages every feature or bug fix into an independent change directory. As a result, AI does not depend on conversation history. It depends on file state. If you stopped halfway through yesterday, you can simply ask AI to read tasks.md again today and continue from the unfinished items.
This capability is especially important for team collaboration. Different contributors can move different changes forward in parallel, then merge them later through sync or bulk-archive, while handling specification conflicts explicitly instead of discovering problems only when code conflicts appear.
A typical workflow for a clear requirement looks like this
/opsx:propose Add rate limiting for the API by IP address and user ID
/opsx:apply add-rate-limiter
/opsx:verify add-rate-limiter
/opsx:archive add-rate-limiterThis flow shows the shortest closed loop from requirement description to implementation, verification, and archiving.
Best practice is not to let AI work alone, but to let AI work within specification constraints
OpenSpec makes the conclusion clear in practice: the clearer the upfront specification, the less rework you face later. Use explore to discover boundaries, proposal/specs/design to narrow disagreements, tasks to break execution into steps, and verify to confirm that the result has not drifted away from the original intent.
Another recommendation that teams often overlook is to start a fresh conversation when running apply. Planning context and implementation context should remain isolated. Otherwise, exploration noise can contaminate the generated result. For complex engineering work, this step is critical.
The minimum governance rules teams should adopt
# Check progress on active changes every day
openspec list
# Run a consistency check before archiving
/opsx:verify <change-name>These actions help teams evolve OpenSpec from a personal productivity tool into a shared knowledge base.
FAQ
What is the core difference between OpenSpec and Spec Kit?
OpenSpec is better suited to incremental development in existing codebases. Its documentation is lighter, its workflow is more flexible, and it supports merging Delta Specs back into the primary spec. Spec Kit is better suited to greenfield projects that start from scratch and follow a more linear process.
Why does OpenSpec reduce AI hallucinations?
Because AI no longer depends on verbal descriptions inside long conversations. Instead, it depends on persistent specification, design, and task files. The input is more stable, the boundaries are clearer, and the generated output becomes more controllable.
What should a team do first when adopting OpenSpec?
Initialize the project first, then complete the project context in config.yaml, and start with a small but concrete real-world requirement as a pilot. Do not try to cover the entire project on day one. Let the primary spec grow gradually through the archive process.
[AI Readability Summary] This article systematically reconstructs OpenSpec’s core concepts, directory structure, command system, and implementation workflow. It highlights how Markdown specification artifacts reduce context poisoning and hallucinations in AI coding, making OpenSpec a strong fit for spec-driven development in existing codebases.