openspec使用指南
# OpenSpec 是什么（在 Cursor 里用来干嘛）
OpenSpec 是一种**规范驱动开发（Spec-Driven Development）**的工作流工具：先把“要做什么、为什么做、怎么验收、怎么实现、怎么拆任务”写成结构化制品（Markdown/YAML），再让 Cursor 的 AI 按制品一步步产出代码并自检，减少“AI 写着写着跑偏/返工多/改动不可追踪”的问题。
你可以把它理解成：给 AI 一个项目内的“作业说明书 + 任务清单 + 验收标准”，并且这些内容会随着开发过程持续迭代、可回溯、可归档。
# 安装与初始化（只做一次）
# 0）macOS 前置条件（Node.js / npm）
OpenSpec 的 CLI 通过 npm 安装，因此你需要先有 Node.js 环境。
node -v
npm -v
2
如果你还没装 Node.js，常见方式是用 Homebrew 安装（或使用 nvm 管理多版本 Node）。
# 1）安装 CLI
如果你用的是官方 OpenSpec（Fission-AI/OpenSpec）：
npm install -g @fission-ai/openspec@latest
openspec --version
2
可选：在 macOS（zsh）里安装命令补全（更好用）：
openspec completion install
# 2）在项目里初始化（生成 Cursor 所需的技能/命令）
在你的仓库根目录运行：
openspec init --tools cursor
初始化后，项目里通常会出现这些内容（不同版本可能略有差异）：
openspec/specs/：项目“长期有效”的规格说明（事实来源）changes/：每次要做的变更（一个变更一个目录）config.yaml：OpenSpec 项目配置（schema、上下文、规则等）
.cursor/skills/：Cursor 用来识别 OpenSpec 能力的技能文件.cursor/commands/：Cursor 的 OPSX 命令文件（用于在聊天输入框里触发工作流）
如果你更新了 OpenSpec 版本，建议在项目里再跑一次：
openspec update
# 在 Cursor 里怎么用（最短闭环）
OpenSpec 的常见闭环是：
- 探索：把需求/方案想清楚
- 提案与制品生成：生成 proposal/specs/design/tasks
- 实施：按 tasks 写代码
- 校验：检查“实现是否符合制品”
- 归档：把这次变更收口，留下可追溯记录
下面给一条“最短上手路径”（建议第一次就按这个跑通）。
# 场景：拿到一个新项目，想让它先“阅读项目”再自动生成文件
你在 Cursor 聊天输入框里，主要就用下面两条（先选一种即可）：
- 引导式（第一次推荐）：
/opsx-onboard（或/opsx:onboard）- 会先阅读你的仓库，并带你走完一次完整流程
- 直接生成制品文件（最常用）：
/opsx-propose <变更描述>（或/opsx:propose ...）- 会读取代码库作为上下文，然后在
openspec/changes/<change>/里生成proposal/specs/design/tasks等文件
- 会读取代码库作为上下文，然后在
注意：OpenSpec 生成文件是围绕某个 change（变更） 来做的，所以你需要给它一句“要做什么”的描述（例如新增功能/修复 bug/重构模块）。
# 可直接复制的输入框示例
/opsx-onboard
/opsx-propose 给现有登录流程增加“图形验证码”，并补齐错误提示与验收标准
/opsx-propose refactor-api-client 把 fetch 封装统一到一个模块，并给出迁移任务清单
# 0）确认 Cursor 里命令前缀（很重要）
不同集成会出现两种写法之一：
- 冒号风格：
/opsx:propose、/opsx:apply… - 短横线风格（Cursor 常见）：
/opsx-propose、/opsx-apply…
你在 Cursor 聊天输入框里打一个 /opsx，看自动补全出来的是哪一种，用你看到的那种即可。
# 0.5）新项目初始化（终端执行一次）
在项目根目录执行：
# 1) 安装（若已安装可跳过）
npm install -g @fission-ai/openspec@latest
# 2) 初始化 Cursor 集成（生成 .cursor/commands 与 .cursor/skills）
openspec init --tools cursor
# 3) 升级后/命令缺失时，重新生成一次
openspec update
2
3
4
5
6
7
8
然后 重启 Cursor，回到聊天框输入 /opsx 检查命令是否出现。
# 1）先探索（可选但强烈推荐）
当你还没想清楚改什么、或者需要先读代码/对比方案时：
/opsx:explore（或/opsx-explore）
这一步的目标不是产出文件，而是把问题范围、约束、验收标准先聊清楚，避免后面制品写一堆最后全推翻。
# 1.5）想“自动读项目并带你跑一遍”？用引导式命令（推荐第一次）
/opsx:onboard（或/opsx-onboard）
它会先扫描你的仓库，再引导你完成一次完整闭环：创建变更 → 生成制品 → 实施 → 校验 → 归档。
# 2）一键创建变更并生成规划制品（推荐起手式）
直接在 Cursor 聊天里输入：
/opsx:propose add-dark-mode
add-dark-mode 也可以换成一句中文描述（例如“给文章页增加目录吸顶”）。执行后会在 openspec/changes/<change>/ 下生成一组规划制品，常见包括：
proposal.md：为什么做、影响面、风险/回滚specs/**：可验证的需求（场景/验收标准）design.md：技术方案与关键决策tasks.md：可执行任务清单（一般是复选框）
补充：如果你想“只生成文件（proposal/specs/design/tasks）先不写代码”，就先停在这一步，打开这些文件审一下、改一下，再进入 /opsx:apply。
# 3）按任务实施写代码
当 tasks.md 已经准备好之后：
/opsx:apply（或/opsx-apply）
OpenSpec 会引导 AI 逐项完成 tasks，并将完成项打勾。中途被打断也没关系，下次继续 /opsx:apply 通常会从未完成任务接着做。
# 4）校验“实现是否符合制品”
/opsx:verify（或/opsx-verify）
它会从三个角度检查并给出问题清单：
- 完整性：任务是否都做了、需求是否都覆盖
- 正确性：实现是否符合 specs 的意图、边界情况是否处理
- 一致性：代码结构是否反映 design 的决策（命名/模式/约定）
# 5）归档本次变更（收口）
/opsx:archive（或/opsx-archive）
归档的意义是把这次变更从“进行中 changes”转成“历史记录”，并在需要时把增量规格合并回主 openspec/specs/（不同配置下可能会提示你同步）。
# 想更“可控”？使用扩展工作流命令
上面的 /opsx:propose 是“最快路径”。如果你希望每个制品都能一份一份生成、边看边改，可以启用扩展命令（不同版本叫法可能略不同，但思路一致）：
- 先创建变更骨架：
/opsx:new - 按依赖逐个生成制品：
/opsx:continue - 一次性快速生成全部规划制品：
/opsx:ff - 把增量 specs 合并回主 specs（可选）：
/opsx:sync - 批量归档多个变更（适合并行变更）：
/opsx:bulk-archive - 引导式教程：
/opsx:onboard
如果你在 Cursor 里看不到这些命令，通常是因为当前 profile 只启用了 core 工作流。你可以在终端里调整（以官方 OpenSpec 为例）：
openspec config profile
openspec update
2
然后回到 Cursor 再试 /opsx 的自动补全。
# openspec/config.yaml：让 AI 更懂你的项目（强烈建议写）
OpenSpec 生成制品的质量，很大程度取决于你给它的“项目上下文”。你可以在 openspec/config.yaml 里写：
- schema：默认工作流（常见是
spec-driven） - context：技术栈、目录结构、命名约定、测试框架、发布流程等
- rules：对不同制品的额外要求（例如 specs 必须 Given/When/Then、proposal 必须包含回滚方案）
它的目标是把你平时口头会说的“我们项目是这样写的”固化下来，减少 AI 猜测。
# 常见问题与排查
# 1）Cursor 里输入 /opsx... 没反应/没有补全
可以按这个顺序排：
- 确认项目初始化过：仓库里是否有
openspec/、.cursor/skills/、.cursor/commands/ - 重新生成：运行
openspec update - 重启 Cursor：部分情况下需要重启让命令/技能重新被索引
# 2）命令写法不对（冒号还是短横线？）
Cursor 常见是短横线：
/opsx-propose、/opsx-apply
但有些文档会写成冒号：
/opsx:propose、/opsx:apply
以你 Cursor 的 / 自动补全为准。
# 3）找不到 change / 不知道当前在操作哪个变更
- 在命令后面显式指定变更名（例如
/opsx-apply add-dark-mode） - 或者用 CLI 看一眼当前变更列表（官方 OpenSpec）：
openspec list
openspec status --json
2
# 4）生成的制品质量一般、太空泛
通常是因为 context 太少或验收标准不清晰：
- 在
proposal/specs里补充边界条件、非功能性要求（性能/可用性/兼容性） - 把“验收标准”写成可检查的条目（页面上看到什么、接口返回什么、哪些错误要提示）
- 在
openspec/config.yaml的rules里强制格式（例如 Given/When/Then）
# 一个最小示例（你可以直接照着跑）
在 Cursor 聊天里：
/opsx-explore：先确认“要改什么、验收是什么”/opsx-propose improve-blog-search：生成制品- 打开
openspec/changes/improve-blog-search/tasks.md看任务清单 /opsx-apply improve-blog-search：按任务实现/opsx-verify improve-blog-search：对齐制品/opsx-archive improve-blog-search：归档
跑通一次后，你就能把它当作日常开发的默认流程：先写清楚，再动手；写完能对照验收；最后能追溯。
# 示例脚本（macOS / zsh）：一键初始化 OpenSpec（新项目常用）
把下面脚本保存为 openspec-bootstrap.zsh，在项目根目录执行：
chmod +x ./openspec-bootstrap.zsh
./openspec-bootstrap.zsh
2
脚本内容：
#!/usr/bin/env zsh
# OpenSpec 一键初始化脚本（macOS / zsh）
# 用途：把“检查环境 → 安装 openspec → init Cursor 集成 → update 生成文件”串起来，避免漏步骤。
set -euo pipefail
# [可选] 如果你不想每次都升级 openspec，可以把第 2 步删掉（保留 init/update 即可）。
echo "[1/4] Check Node.js & npm"
# 1) 检查 node/npm 是否存在；没有就提示安装（OpenSpec 通过 npm 安装）
command -v node >/dev/null 2>&1 || { echo "node not found. Please install Node.js first."; exit 1; }
command -v npm >/dev/null 2>&1 || { echo "npm not found. Please install npm first."; exit 1; }
node -v
npm -v
echo "[2/4] Install/Upgrade OpenSpec CLI"
# 2) 安装/升级 OpenSpec CLI（全局）
npm i -g @fission-ai/openspec@latest
openspec --version
echo "[3/4] Init OpenSpec for Cursor (run in project root)"
# 3) 初始化项目（生成 openspec/ 目录 + Cursor 所需的 .cursor/commands/.cursor/skills）
# 如果你还想同时生成其他工具集成，可以改成：openspec init --tools cursor,claude
openspec init --tools cursor
echo "[4/4] Update generated Cursor files"
# 4) 重新生成指令文件（常用于 CLI 升级后、命令缺失/不更新时）
openspec update
cat <<'EOF'
Done.
Next (in Cursor Chat):
- Type "/opsx" and pick the autocomplete commands.
- Recommended first run: /opsx-onboard
- Or generate artifacts directly: /opsx-propose <your-change-description>
Tips:
- If you can't see opsx commands, restart Cursor after init/update.
- Use the exact command style Cursor suggests: /opsx-xxx or /opsx:xxx
EOF
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# 常用命令速查（Cursor 输入框）
以 Cursor 输入框
/opsx的自动补全为准：你看到的是/opsx-xxx就用短横线；如果是/opsx:xxx就用冒号。
# 快速闭环（最常用）
- 创建变更 + 自动生成规划制品：
/opsx-propose <变更描述或变更名> - 按 tasks 实施：
/opsx-apply [change-name] - 校验实现与制品一致：
/opsx-verify [change-name] - 归档变更（收口）：
/opsx-archive [change-name]
示例：
/opsx-propose 给文章页增加目录吸顶，并补齐验收标准
/opsx-apply
/opsx-verify
/opsx-archive
2
3
4
# 先读项目再开始（适合第一次）
- 引导式完整流程：
/opsx-onboard - 探索/调研（不产出制品）：
/opsx-explore [topic]
示例：
/opsx-onboard
/opsx-explore 这个项目的鉴权是怎么做的？有哪些入口？
# 更可控的制品生成（逐步/批量）
- 只创建变更骨架：
/opsx-new [change-name] - 创建下一个制品：
/opsx-continue [change-name] - 一次生成所有规划制品：
/opsx-ff [change-name]
# 维护与合并
- 同步增量 specs 到主 specs（可选）：
/opsx-sync [change-name] - 批量归档多个变更：
/opsx-bulk-archive [change-names...]