OpenSpec 使用教程

OpenSpec 是一个用于 AI 编程的规范驱动开发（Spec-Driven Development, SDD）框架。它通过“先写规范再写代码”的方式，让 AI 编码工具（如 Cursor、Copilot、Claude Code）按照明确的需求生成代码，从而减少 AI 乱写代码的问题。 (OpenSpec)

下面给你一份 从安装到实际使用的完整入门教程。

---

一、OpenSpec 是什么（简单理解）

OpenSpec 的核心思想：

先写规范 → 再生成代码 → 再归档规范

这样 AI 写代码时就会严格按照规范执行，而不是根据随意的 prompt。 (GitHub)

典型流程：

1. 创建功能变更（Change）
2. 生成需求 / 设计 / 任务
3. AI 按任务实现代码
4. 完成后归档

---

二、安装 OpenSpec

1 安装 Node.js

需要 Node.js ≥ 20.19

检查版本：

node -v

---

2 安装 OpenSpec

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

或者

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

安装完成后测试：

openspec --help

---

三、初始化项目

进入你的项目目录：

cd my-project

初始化：

openspec init

项目会生成一个目录：

openspec/
 ├─ specs/      # 当前系统规范
 ├─ changes/    # 新功能变更
 ├─ AGENTS.md   # AI助手规则
 └─ config.yaml

这里的逻辑：

文件夹	作用
specs	当前系统功能规范
changes	新功能计划
AGENTS.md	AI工作规则

---

四、OpenSpec 基本工作流程

1 创建一个功能 Change

例如新增 暗黑模式：

/opsx:new add-dark-mode

会创建：

openspec/changes/add-dark-mode/

里面包含：

proposal.md
design.md
tasks.md

---

2 生成规划文档

使用：

/opsx:ff

AI 会自动生成：

• proposal.md（需求）
• design.md（设计）
• tasks.md（任务列表）

例如 tasks.md：

1. Add theme config
2. Create dark CSS
3. Add toggle button
4. Persist user preference

---

3 AI 实现代码

运行：

/opsx:apply

AI会按 tasks 一条一条完成代码。

---

4 完成后归档

功能完成后：

/opsx:archive

作用：

• 更新 specs
• 归档 change
• 项目规范同步

---

五、典型开发流程示例

例如开发一个 登录功能：

① 创建 change

/opsx:new add-login

---

② AI生成规划

/opsx:ff

生成：

proposal.md
design.md
tasks.md

---

③ AI开发

/opsx:apply

执行：

1 create login API
2 create auth service
3 add login UI
4 add JWT validation

---

④ 归档

/opsx:archive

系统规范更新。

---

六、常用命令

命令	作用
openspec init	初始化项目
openspec update	更新 AI 指令
openspec list	查看 changes
openspec view	查看规范
/opsx:new	创建 change
/opsx:ff	生成规划
/opsx:apply	实现代码
/opsx:archive	归档

---

七、OpenSpec 最适合的场景

非常适合：

• AI编程（Cursor / Claude Code）
• 大型项目
• 需要规范开发
• 多人协作

不太适合：

• 小脚本
• 一次性代码

---

八、OpenSpec vs 普通 AI 编程

普通方式：

Prompt -> AI写代码 -> 经常写错

OpenSpec：

Spec -> Design -> Tasks -> Code

优点：

• AI更稳定
• 功能更完整
• 不容易漏需求

---

💡 一句话总结

OpenSpec = 给 AI 写代码之前先写“产品需求文档”。

---

如果你需要，我可以再给你：

• OpenSpec + Cursor 完整实战教程（最常见）
• OpenSpec 项目结构详解
• 5分钟学会 OpenSpec 的完整 workflow
  这些会比官方文档更容易上手。