Cursor 安装 OpenSpec 使用教程

OpenSpec 是一套**规格驱动（Spec-Driven）**的 AI 协作工作流：先把「为什么做、做什么、怎么做、任务清单」写进仓库 Markdown，再让 Cursor Agent 按清单实现，避免需求在聊天中漂移。
官方仓库：Fission-AI/OpenSpec

---

目录

1. 什么是 OpenSpec
2. 安装与初始化
3. 命令与工作流
4. Artifact 写作指南
5. 目录结构与生命周期
6. 实战示例
7. Verify、Archive 与规格同步
8. 与 Cursor 集成
9. 团队协作
10. 最佳实践与反模式
11. CLI 参考
12. 常见问题

---

1. 什么是 OpenSpec

1.1 解决什么问题

痛点	OpenSpec 的做法
需求只在聊天里，换会话就丢	写入 openspec/changes/<name>/ 持久化
AI 直接写代码，边界不清	先写 Spec（WHEN/THEN 可测场景）再实现
大需求一次改太多	tasks.md 拆成小 checkbox，逐条 /opsx-apply
事后不知道为什么这么设计	Archive 归档，保留 proposal / design 决策史
多人协作口径不一致	openspec/specs/ 作为项目级「规格真相源」
Code Review 缺验收标准	Spec 场景可直接当作 Review Checklist

1.2 与传统「直接让 AI 写代码」的对比

维度	直接写代码	OpenSpec
需求存放	聊天上下文	仓库 Markdown
验收标准	模糊	Spec 场景（WHEN/THEN）
换 Agent / 换人	易断层	读 changes/<name>/ 即可续上
大需求可控性	低	高（tasks 拆分）
历史决策	难追溯	archive 可查

OpenSpec 不是替代编码，而是加一层可 Review、可验收、可归档的规格层。小改动可跳过；跨文件、需留痕的需求越值得用。

1.3 适用场景

适合	不太适合
新接口、新模块、跨多文件改造	改一行注释、纯格式化
需要留痕、可验收的业务需求	紧急 hotfix 且无需文档
团队「先规格、后代码」	探索性 spike（用 Explore 即可，不必全套 artifact）

---

2. 安装与初始化

2.1 环境要求

项	要求
Node.js	≥ 20.19.0
包管理器	npm / pnpm / yarn / bun 任选
Cursor	已安装，Agent 模式可用
Git	建议项目已纳入版本管理

node -v          # 预期 v20.19.0 或更高
openspec --version

若 openspec 未找到，见 Q1。

2.2 安装 CLI

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

升级后刷新 Cursor 集成文件：

openspec update

2.3 在项目中初始化

cd D:\path\to\your-project
openspec init --tools cursor

openspec init 也可交互式运行，勾选 Cursor 即可。初始化会生成：

• openspec/ — 规格与变更目录
• .cursor/commands/opsx-*.md — 斜杠命令
• .cursor/skills/openspec-*/ — Agent Skills
• AGENTS.md（若生成）— 供 AI 读取的项目约定

建议首次 init 后提交 Git，便于团队共享命令与 Skills。

2.4 确认命令与首次体验

在 Agent 聊天框输入 /，应出现 opsx-propose、opsx-apply 等命令（文件名带连字符，输入 /opsx- 后选择即可）。

命令未出现时：确认用 Open Folder 打开项目根目录 → 执行 openspec init --tools cursor → 重启 Cursor。

首次使用建议运行：

/opsx-onboard

约 15～20 分钟走完完整流程：探索 → 提案 → 规格 → 设计 → 任务 → 实现 → 归档。

---

3. 命令与工作流

3.1 命令一览

命令	作用	何时使用
/opsx-explore	探讨方案，不改代码	方案未定时摸底
/opsx-propose	一步生成全部 artifact	需求清晰，想快速出文档
/opsx-new	新建 change，逐步写 artifact	需求复杂，每步需确认
/opsx-continue	继续未完成的 change	artifact 写到一半
/opsx-ff	Fast-forward，快速补全 artifact	change 已有，缺 design/specs/tasks
/opsx-apply	按 tasks.md 写代码	tasks 已 Review 通过
/opsx-verify	对照 spec 检查实现	实现完成后、归档前
/opsx-archive	归档已完成 change	verify 通过或确认可收尾
/opsx-onboard	交互式新手引导	首次体验

用法示例：/opsx-propose add-user-auth（变更名使用 kebab-case：add-user-auth ✅，AddUserAuth ❌）

3.2 命令选型

3.3 标准流程

1. /opsx-propose <变更名或描述>
2. Review openspec/changes/<name>/ 下文档
3. /opsx-apply <name>
4. /opsx-verify <name>（建议）
5. /opsx-archive <name>

OpenSpec 不锁阶段：Apply 过程中发现 spec 不对，可回头改 artifact 再继续 apply。

3.4 中断恢复

停在哪	恢复方式
change 已建，artifact 未写完	/opsx-continue <name> 或 /opsx-ff <name>
代码写了一半	/opsx-apply <name>（从未完成任务继续）
实现中发现设计有问题	先改 design.md / specs/，再 apply

3.5 Artifact 一览

文件	回答的问题
proposal.md	为什么做？影响谁？
specs/**/spec.md	做什么？如何验收？
design.md	怎么做？技术决策？
tasks.md	按什么顺序做？

---

4. Artifact 写作指南

4.1 Proposal

# <变更标题>

## Why
（1～3 句话：问题 / 机会 / 不做的风险）

## What Changes
- 变更点 1
- 变更点 2

## Capabilities

### New Capabilities
- `capability-name`: 一句话说明

### Modified Capabilities
- `existing-capability`: 修改说明（若无则写「无」）

## Impact
- **代码**：涉及模块 / 文件类型
- **API**：新增或变更的接口
- **兼容性**：向后兼容策略
- **风险**：需要回归的点

4.2 Spec（核心）

使用 Requirement + Scenario，场景必须可测试：

## ADDED Requirements

### Requirement: 用户登录接口返回 Token

系统 MUST 在校验通过后返回 JWT，失败时返回统一错误结构。

#### Scenario: 用户名密码正确
- **WHEN** 客户端 POST `/api/auth/login` 且账号密码正确
- **THEN** 响应 HTTP 200
- **AND** 响应体包含 `token` 与 `expiresIn`

#### Scenario: 密码错误
- **WHEN** 密码不正确
- **THEN** 响应 HTTP 401
- **AND** 不签发 token

Delta Spec 段落：

段落	含义
## ADDED Requirements	新增能力
## MODIFIED Requirements	修改已有能力（写完整更新后内容）
## REMOVED Requirements	删除的能力
## RENAMED Requirements	重命名（FROM / TO）

4.3 Design

# Design: <变更名>

## Context
（当前系统状态、约束、相关模块）

## Goals / Non-Goals

**Goals:**
- 目标 1

**Non-Goals:**
- 明确不做什么（防止 Agent 过度实现）

## Decisions

### Decision 1: <决策标题>
（方案 + 理由 + 备选方案为何未选）

## Risks / Trade-offs
| 风险 | 缓解 |
|------|------|
| ... | ... |

4.4 Tasks

## 1. 接口层
- [ ] 1.1 新增 XxxController，暴露 POST /api/...
- [ ] 1.2 入参校验与统一异常

## 2. 业务层
- [ ] 2.1 实现 XxxService 核心逻辑
- [ ] 2.2 单元测试覆盖 Scenario A / B

## 3. 验证
- [ ] 3.1 本地联调通过
- [ ] 3.2 对照 spec 场景逐项勾选

写好 tasks 的原则：每条可在一次 Agent 回合内完成；顺序体现依赖（接口 → 实现 → 测试）；验证章节与 spec 场景对应。

---

5. 目录结构与生命周期

your-project/
├── openspec/
│   ├── specs/                         # 主规格（长期真相源）
│   │   └── <capability>/spec.md
│   ├── changes/
│   │   ├── <active-change>/           # 进行中
│   │   └── archive/
│   │       └── YYYY-MM-DD-<name>/     # 已完成
│   └── config.yaml                    # 可选
├── .cursor/
│   ├── commands/                      # /opsx-* 命令
│   ├── skills/                        # Agent Skills
│   └── rules/                         # 可选项目规则
└── AGENTS.md                          # 可选：AI 协作约定

状态	位置	说明
进行中	openspec/changes/<name>/	可改 artifact、可 apply
已归档	openspec/changes/archive/YYYY-MM-DD-<name>/	只读历史；能力已合并到 specs/
主规格	openspec/specs/	当前系统「应该是什么样」

---

6. 实战示例

中等规模：新增用户认证

/opsx-propose add-user-auth
/opsx-apply add-user-auth
/opsx-verify add-user-auth
/opsx-archive add-user-auth

产出：proposal.md（为何用 JWT）→ specs（login、token-refresh）→ design（鉴权中间件）→ tasks（接口 → Service → 测试）。

边界 Bug：分页 total 不一致

/opsx-explore                          # 可选：先定位根因
/opsx-propose fix-pagination-total-count
/opsx-apply fix-pagination-total-count

Proposal 的 Why 写清现象与影响；tasks 聚焦「统一 list 与 count 的查询条件」和回归场景。

并行多个 change

openspec list

建议同一时间 focus 一个 change，apply / verify 时显式带变更名，避免 Agent 混用不同 spec。

---

7. Verify、Archive 与规格同步

Verify

/opsx-verify add-user-auth

维度	检查内容
Completeness	tasks 是否全部 [x]；spec 需求是否有实现
Correctness	实现是否符合 Scenario 的 WHEN/THEN
Coherence	是否违背 design 决策与项目惯例

有 CRITICAL 时，继续 /opsx-apply 或手动补全后再 verify，通过后再 archive。

Archive

/opsx-archive add-user-auth

Archive 会：将 change 移入 archive/YYYY-MM-DD-<name>/；把 delta spec 合并进 openspec/specs/；保留决策历史。

CLI 等价命令：openspec archive add-user-auth

Sync Specs

若 spec 已稳定但代码仍在开发，可先请求将 delta spec 同步到 openspec/specs/（对应 skill：openspec-sync-specs），稍后再 archive。

---

8. 与 Cursor 集成

层级	作用
AGENTS.md	测试命令、分支策略、目录约定
.cursor/rules/	分层、命名、禁止事项
openspec/changes/<name>/	本次变更的 spec / tasks（当次需求真相源）

Apply 时 @ 引用关键文件，减少 Agent 偏离：

@openspec/changes/add-user-auth/tasks.md
@openspec/changes/add-user-auth/specs/user-auth-login/spec.md
@openspec/changes/add-user-auth/design.md

/opsx-apply add-user-auth

可在 .cursor/rules/ 中约定：跨文件需求走 OpenSpec；Apply 必须对照 tasks 勾选；Spec 场景缺失 THEN 视为不完整。

---

9. 团队协作

一个 PR 建议包含： 业务代码 + openspec/changes/<name>/ 完整 artifact + tasks 已完成项均为 [x]。

Reviewer Checklist：

• Proposal 的 Why 是否成立？
• 每个 Requirement 至少有一个 Scenario？
• Design 的 Non-Goals 是否防止 scope 膨胀？
• 代码 diff 是否超出 proposal 的 Impact 范围？

多人并行： 一人一个 change 目录；specs/<capability>/ 合并时注意能力名冲突；完成后 archive 再开新 change。

---

10. 最佳实践与反模式

最佳实践	反模式 → 改进
Spec 用 WHEN/THEN/AND，可当测试用例	只有 tasks 没有 spec → 补 spec 场景
Design 写 Non-Goals，防过度实现	spec 写实现细节 → 细节放 design
Tasks 粒度小，每步 apply 可控	一个 change 包太多能力 → 拆多个 change
Apply 前 @ tasks 和 specs	改代码不更新 tasks → 同步勾选
归档前 verify	从不 archive → changes/ 堆积
变更名 kebab-case	所有小事都走 OpenSpec → 直接改或短 proposal

---

11. CLI 参考

命令	说明
openspec init [--tools cursor]	初始化项目
openspec update	升级后刷新 Cursor 集成
openspec new change "<name>"	创建 change
openspec list	列出 active changes
openspec status --change "<name>"	artifact 完成度
openspec instructions <artifact> --change "<name>"	查看写作模板
openspec archive "<name>"	归档
openspec schemas	查看可用工作流 schema

openspec list
openspec status --change add-user-auth
openspec instructions proposal --change add-user-auth

---

12. 常见问题

Q1：openspec: command not found

• 执行 npm install -g @fission-ai/openspec@latest
• Windows：确认 %AppData%\npm 在 PATH 中
• 新开终端再试 openspec --version

Q2：Cursor 里没有 /opsx-*

• 项目根执行 openspec init --tools cursor
• 确认 .cursor/commands/opsx-propose.md 存在
• 用 Open Folder 打开项目根，不要只开子目录
• 重启 Cursor；升级 CLI 后执行 openspec update

Q3：/opsx-apply 提示 blocked

• openspec status --change "<name>" 查看缺哪个 artifact
• /opsx-continue <name> 或 /opsx-ff <name> 补文档

Q4：Agent 实现偏离 spec

• Apply 时 @ tasks.md + specs/
• 检查 design 的 Non-Goals；拆小 change；先改 artifact 再 apply

Q5：Verify 报 CRITICAL

• 未完成 tasks → 继续 apply
• 缺 requirement 实现 → 补代码或修正 spec
• 与 design 冲突 → 更新 design 或改代码

Q6：OpenSpec 和单元测试的关系？

Spec 场景是验收测试的文字版；implement 后应在 tasks 中要求落地为自动化测试。

---

相关链接

• OpenSpec GitHub
• Getting Started
• CLI 参考
• npm：@fission-ai/openspec