OpenSpec

OpenSpec

https://github.com/Fission-AI/OpenSpec

OpenSpec 介绍

比 Cursor Plan 更细、比 Spec-kit 更轻；是一套轻量级的规格化工作流

特点：

• 无需 API 密钥：完全本地运行，不依赖外部服务
• 规格先行：通过结构化的变更文件夹（提案、任务、规格更新）让项目范围明确且可审计
• 工具兼容性强：支持 Claude Code、Cursor、GitHub Copilot、Droid 等多种 AI 编码智能体，既可以通过自定义斜杠命令使用，也可以通过上下文规则集成
• 适合成熟项目：特别擅长处理现有功能的修改（1→n），而不仅仅是从零开始的新功能

OpenSpec 工作流程

┌────────────────────┐
│ Draft Change       │
│ Proposal           │
└────────┬───────────┘
         │ share intent with your AI
         ▼
┌────────────────────┐
│ Review & Align     │
│ (edit specs/tasks) │◀──── feedback loop ──────┐
└────────┬───────────┘                          │
         │ approved plan                        │
         ▼                                      │
┌────────────────────┐                          │
│ Implement Tasks    │──────────────────────────┘
│ (AI writes code)   │
└────────┬───────────┘
         │ ship the change
         ▼
┌────────────────────┐
│ Archive & Update   │
│ Specs (source)     │
└────────────────────┘

1. Draft a change proposal that captures the spec updates you want.
2. Review the proposal with your AI assistant until everyone agrees.
3. Implement tasks that reference the agreed specs.
4. Archive the change to merge the approved updates back into the source-of-truth specs.

1. 起草变更提案 - 捕获你想要的规格更新
2. 审查对齐 - 与 AI 助手反复沟通直到达成共识
3. 实施任务 - AI 根据约定的规格编写代码
4. 归档更新 - 将已批准的更新合并回源规格文档

OpenSpect 基础

项目结构

OpenSpec 使用双文件夹模型：

· openspec/specs/ - 存放当前真实的系统规格

· openspec/changes/ - 存放提议中的变更

每个变更包含：提案文档、任务清单、可选的设计文档，以及规格增量（delta）

适用场景

• 需要多人协作且需要明确需求的项目
• 需要追溯功能演变历史的系统
• 希望 AI 助手输出更可控、可审查的团队
• 正在维护和扩展现有代码库（而非从零开始）

常用命令

openspec list               # View active change folders
openspec view               # Interactive dashboard of specs and changes
openspec show <change>      # Display change details (proposal, tasks, spec updates)
openspec validate <change>  # Check spec formatting and structure
openspec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)

• 初始化

openspec init

• 查看 dashboard

openspec view

• 查看 archive

openspec list

OpenSpec 生成的产物

openspec/
├── specs/
│   └── auth/
│       └── spec.md           # Current auth spec (if exists)
└── changes/
    └── add-2fa/              # AI creates this entire structure
        ├── proposal.md       # Why and what changes
        ├── tasks.md          # Implementation checklist
        ├── design.md         # Technical decisions (optional)
        └── specs/
            └── auth/
                └── spec.md   # Delta showing additions

OpenSpec 使用

快速入门

# In Cursor, just type:
/openspec-proposal Add user authentication with 2FA

# AI creates the full structure:
# - proposal.md (what and why)
# - tasks.md (implementation checklist)  
# - spec deltas (what changes in your system)

# Review, iterate, then:
/openspec-apply add-user-auth

# AI implements following the agreed specs

# When done:
/openspec-archive add-user-auth

示例

1、 Draft the Proposal

让 AI 创建 change proposal

Create an OpenSpec change proposal for adding profile search filters by role and team
# 或者
Shortcut for tools with slash commands: /openspec:proposal Add profile search filters

2、Verify & Review

• 校验 change 是否正确
• review proposal

openspec list                             # Confirm the change folder exists
openspec validate add-profile-filters     # Validate spec formatting
openspec show add-profile-filters         # Review proposal, tasks, and spec delta

3、Refine the Specs

反复修改 spec，直到满足您的需求：

Can you add acceptance criteria for the role and team filters?

4、Implement the Change

一旦 spec 看起来不错，就开始实施：

You: The specs look good. Let's implement this change.
     (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)

AI:  I'll work through the tasks in the add-profile-filters change.
     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓…*

5、 Archive the Completed Change

实施完成后，归档更改：

AI:  All tasks are complete. The implementation is ready.

You: Please archive the change
     (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)

AI:  I'll archive the add-profile-filters change.
    *Runs: openspec archive add-profile-filters --yes*
     ✓ Change archived successfully. Specs updated. Ready for the next feature!

或者自己在终端中运行该命令：

$ openspec archive add-profile-filters --yes  # Archive the completed change without prompts

1. 支持原生斜杠命令（slash commands）的工具（如 Claude Code、Cursor、Codex），可使用展示的快捷键操作。
2. 其他所有工具，需通过自然语言请求操作，具体可使用 “create an OpenSpec proposal”， “apply the OpenSpec change” 或 “archive the change” 等表述。