How OpenSpec Enables Spec‑Driven Development with AI Collaboration

1. Introduction

OpenSpec ( https://github.com/Fission-AI/OpenSpec) is a CLI tool that enables a spec‑driven workflow between developers and AI assistants, emphasizing change isolation, human‑AI consensus, and a review loop.

2. Core Concepts

The workflow consists of two stages:

Define what is needed by creating specifications in openspec/specs/.

Manage how to change by placing change proposals in openspec/changes/.

3. Setup

Install OpenSpec

// Requires Node >= 20.19.0
npm install -g @fission-ai/openspec@latest

Initialize a project

# Go to the project root (prefer a new branch)
cd your_project
# If the command is missing, use npx
openspec init

Fill project context

Prompt the AI (e.g., Cursor) with:

Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions.

The AI generates project.md containing purpose, tech stack, conventions, architecture, testing strategy, git workflow, domain context, constraints, and external dependencies.

4. Propose a change

In the Cursor dialog run the slash command /openspec-propose followed by the requirement document URL, for example:

/openspec-propose https://mi.feishu.cn/wiki/XrYcwaeD6ijfBSk

This creates a directory under openspec/changes/ with the core files: proposal.md – why, what, impact. design.md – technical solution and architecture decisions. tasks.md – checklist of implementation tasks. specs/.../spec.md – testable requirement spec.

5. Review and iterate

Edit tasks.md or add comments to refine the proposal. Example of updating a task:

@openspec/changes/support-fuzzy-title-search/tasks.md 当关键字小于2个字时点击查询时给报错“文章标题不能少于2个字”。

6. Apply the change

When the proposal meets expectations, execute the apply command in Cursor:

/opsx:apply add-article-management
/opsx:apply support-fuzzy-title-search

7. Archive

After successful testing, archive the change with a date‑prefixed folder:

/opsx:archive add-article-management
/opsx:archive support-fuzzy-title-search

8. Process summary

AI reads the codebase and fills project.md.

Submit a requirement as a change proposal.

Iteratively refine the proposal and tasks.

Apply with /opsx:apply.

Test and archive with /opsx:archive.

9. FAQ

OpenSpec vs. spec‑kit

spec‑kit is better for brand‑new 0‑>1 projects; OpenSpec excels for existing 1‑>n systems with lightweight dual‑folder management and fine‑grained impact tracking.

When to create a new change for a bug?

Simple bugs can be fixed directly. If the fix involves functional changes, architectural changes, API changes, or backward‑compatibility breaks, create a new change proposal:

openspec change create fix-bug-name
# Follow the full flow: proposal → design → tasks → apply → archive

How OpenSpec iterates

Each iteration adds an incremental change on top of the current specs/ directory, archives it, and the next iteration starts from the updated state.

Related repository:

https://github.com/mengday/ruoyi-spec-kit.git (branch: feat_openspec)