OpenSpec 实操指南

上一章讲了规范驱动开发的理念。这一章动手。

OpenSpec 是目前最轻量的规范驱动工具，特别适合个人开发者和小团队。它不像 Spec Kit 那么"重"，也不需要像 Kiro 那样换一个 IDE。你用 Cursor、用 Claude Code、用 Windsurf，都能用 OpenSpec。

这一章的目标是让你完整跑通一个案例，从安装到归档，每个步骤都看到实际效果。

安装和初始化

先确保你的 Node.js 版本是 20.19.0 以上。打开终端，输入 node --version 检查一下。版本太低就升级，版本够了就继续。

全局安装 OpenSpec CLI：

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

安装完成后验证一下：

openspec --version

看到版本号就说明装好了。接下来进入你的项目目录，执行初始化：

cd my-project
openspec init

这时候会出现一个交互界面，问你用什么 AI 工具。它支持的工具很多：Claude Code、Cursor、Windsurf、GitHub Copilot、Amazon Q Developer 等等。选择你常用的那个。

初始化完成后，你的项目里会多出这些东西：

my-project/
├── AGENTS.md              # AI 代理指引文件
└── openspec/
    ├── project.md         # 项目上下文
    ├── specs/             # 源头规范（真相来源）
    ├── changes/           # 变更提案（进行中的改动）
    └── archive/           # 已归档的变更

这几个文件和文件夹，各有各的用处。

理解目录结构

project.md：项目上下文

openspec/project.md 是给 AI 看的项目概览。它告诉 AI 这个项目是干什么的、用了什么技术栈、有什么编码规范。

初始化之后，这个文件是空的或者只有基础模板。你需要填充内容，让 AI 更好地理解你的项目。

一个填写好的 project.md 大概长这样：

# 项目上下文

## 项目概述
这是一个 SaaS 订阅管理平台，允许用户管理他们的软件订阅、追踪费用、设置续费提醒。

## 技术栈
- 前端：Next.js 14 + TypeScript + Tailwind CSS
- 后端：Next.js API Routes + Prisma ORM
- 数据库：PostgreSQL
- 认证：Better Auth
- 支付：Stripe

## 编码规范
- 使用 TypeScript 严格模式
- 组件使用函数式组件 + hooks
- 样式使用 Tailwind，避免内联样式对象
- API 路由使用 RESTful 风格
- 错误处理使用统一的 try-catch 模式

## 目录结构
- /src/app - Next.js App Router 页面
- /src/components - 可复用组件
- /src/lib - 工具函数和配置
- /prisma - 数据库 schema 和迁移

## 约束
- 不使用任何已废弃的 API
- 所有数据库操作必须在服务端
- 敏感信息存储在环境变量中

初始化后，OpenSpec 会提示你：让 AI 帮你填写这个文件。你可以直接告诉 AI：

"请阅读 openspec/project.md，帮我根据项目实际情况填写技术栈、编码规范和目录结构。"

AI 会分析你的项目文件，然后自动填充。省事。

specs/：源头规范

openspec/specs/ 存放的是项目当前的规范——也就是"真相来源"。每个子文件夹代表一个功能模块，里面有一个 spec.md 文件描述这个模块的需求和行为。

一开始这个目录是空的。随着你完成变更并归档，规范会逐渐积累。

changes/：变更提案

openspec/changes/ 是工作区。当你想添加新功能或修改现有功能时，你（或者 AI）会在这里创建一个变更文件夹。

假设你想给应用加一个双因素认证功能，变更文件夹可能叫 add-2fa/，里面包含：

proposal.md — 描述为什么要做这个变更、做什么
tasks.md — 实现这个变更的任务清单
specs/ — 对现有规范的修改（增量形式）
design.md（可选）— 技术设计决策

AGENTS.md：AI 代理指引

项目根目录下的 AGENTS.md 是给 AI 看的操作手册。它告诉 AI 如何使用 OpenSpec 工作流。

不同于给人看的 README.md，AGENTS.md 专门为 AI 编写，包含具体的操作步骤和命令。支持 AGENTS.md 约定的 AI 工具（包括 OpenAI Codex、Cursor、Claude Code 等）会自动读取这个文件。

完整案例：添加用户 2FA 验证

来走一个完整的案例。假设你的项目是一个 SaaS 应用，现在要给用户添加双因素认证功能。

第一步：起草提案

打开你的 AI 工具（Cursor 或者 Claude Code），输入：

创建一个 OpenSpec 变更提案：为用户添加双因素认证（2FA）功能。
用户可以在设置页面开启 2FA，开启后登录时需要输入手机验证码。

如果你用的是 Cursor 并且配置了 OpenSpec 的斜杠命令，可以直接用：

/openspec:proposal 添加用户 2FA 认证功能

AI 会在 openspec/changes/ 下创建一个新目录，比如 add-user-2fa/，里面生成几个文件。

生成的 proposal.md

AI 生成的 proposal.md 大概长这样：

# 变更提案：添加用户 2FA 认证

## 变更 ID
add-user-2fa

## 摘要
为用户账户添加双因素认证（Two-Factor Authentication）功能，
提高账户安全性。

## 动机
当前系统只有密码保护，面临密码泄露风险。
双因素认证可以显著降低账户被盗的可能性。

## 变更范围
- 用户设置页面新增 2FA 开关
- 登录流程增加验证码验证步骤
- 数据库用户表增加 2FA 相关字段
- 新增短信验证码发送和校验接口

## 影响的规范
- auth/spec.md（认证模块）
- user/spec.md（用户模块）

## 验收标准
- 用户可以在设置中开启/关闭 2FA
- 开启 2FA 后，登录需输入 6 位验证码
- 验证码 5 分钟内有效
- 连续 5 次输错验证码锁定账户 30 分钟

生成的 tasks.md

任务清单会被拆得很细：

# 任务清单

## 1. 数据库变更
- [ ] 1.1 用户表添加 `two_factor_enabled` 布尔字段
- [ ] 1.2 用户表添加 `two_factor_secret` 字段（加密存储）
- [ ] 1.3 创建验证码记录表 `otp_codes`
- [ ] 1.4 运行数据库迁移

## 2. 后端 API
- [ ] 2.1 创建 POST /api/auth/2fa/enable 接口
- [ ] 2.2 创建 POST /api/auth/2fa/disable 接口
- [ ] 2.3 创建 POST /api/auth/2fa/send-code 接口
- [ ] 2.4 创建 POST /api/auth/2fa/verify 接口
- [ ] 2.5 修改登录接口，增加 2FA 校验步骤

## 3. 前端界面
- [ ] 3.1 设置页面添加 2FA 开关组件
- [ ] 3.2 创建验证码输入弹窗组件
- [ ] 3.3 修改登录页面，支持 2FA 流程
- [ ] 3.4 添加 2FA 相关的加载和错误状态

## 4. 测试
- [ ] 4.1 2FA 开启/关闭流程测试
- [ ] 4.2 验证码发送和验证测试
- [ ] 4.3 登录流程集成测试
- [ ] 4.4 错误处理和边界情况测试

生成的 spec delta

在 openspec/changes/add-user-2fa/specs/auth/ 目录下，会有一个 spec.md 文件，记录对认证模块规范的增量修改：

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST support optional two-factor authentication for user accounts.

#### Scenario: Enable 2FA
- GIVEN a logged-in user
- WHEN the user enables 2FA in settings
- THEN the system stores the 2FA secret
- AND future logins require OTP verification

#### Scenario: Login with 2FA
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN the system sends an OTP to the user's phone
- AND the user must enter the correct OTP to complete login

#### Scenario: Failed OTP attempts
- GIVEN a user entering OTP
- WHEN the user fails 5 consecutive attempts
- THEN the account is locked for 30 minutes

注意这里使用的是 Delta 格式——## ADDED Requirements 表示这是新增的需求，不是修改现有的。如果是修改，会用 ## MODIFIED Requirements。

第二步：审查和对齐

提案生成后，你需要审查一下。运行：

openspec show add-user-2fa

这会打印出提案的详细内容。你也可以用 openspec validate 检查格式是否正确：

openspec validate add-user-2fa --strict

如果有问题，它会告诉你哪里不对。

审查的时候，重点看几个地方：

验收标准是否完整？ 有没有遗漏的场景？
任务拆分是否合理？ 粒度太大不好执行，太小又太碎。
规范增量是否准确？ ADDED 和 MODIFIED 用对了吗？

如果需要调整，直接告诉 AI：

任务清单里缺少短信服务商集成的任务，请补充。
另外，验收标准里加一条：用户可以查看 2FA 开启历史记录。

AI 会更新相应的文件。来回几轮，直到你满意为止。

第三步：实现任务

规范确认后，开始写代码。告诉 AI：

规范已经确认，请开始实现 add-user-2fa 变更。按照 tasks.md 的顺序执行。

或者用斜杠命令：

/openspec:apply add-user-2fa

AI 会按照任务清单逐个实现。每完成一个任务，就在 tasks.md 里打勾：

## 1. 数据库变更
- [x] 1.1 用户表添加 `two_factor_enabled` 布尔字段
- [x] 1.2 用户表添加 `two_factor_secret` 字段（加密存储）
- [ ] 1.3 创建验证码记录表 `otp_codes`
...

实现过程中，如果 AI 遇到问题或者需要你做决策，它会暂停询问。比如：

"短信服务商选用 Twilio 还是阿里云短信？请确认。"

你给出答案，AI 继续执行。

这个过程可能需要一些时间，取决于功能的复杂度。好处是每一步都有据可查，你知道 AI 在做什么、为什么这么做。

第四步：归档变更

所有任务完成、测试通过后，归档这个变更：

openspec archive add-user-2fa --yes

归档操作会做几件事：

把 changes/add-user-2fa/specs/ 里的增量合并到 specs/ 里
把整个变更文件夹移动到 archive/ 目录
更新相关的规范文档

归档后，openspec/specs/auth/spec.md 就会包含完整的 2FA 需求描述，成为项目规范的一部分。下次再做相关修改，AI 读到这些规范，就知道现有系统是怎么工作的。

Cursor 集成技巧

如果你主要用 Cursor，这里有几个技巧能让 OpenSpec 用得更顺手。

启用斜杠命令

OpenSpec 初始化时选择 Cursor，会自动在项目里创建 .cursor/commands/ 目录，包含预定义的斜杠命令。这样你就可以直接在 Cursor 里用：

/openspec:proposal — 创建新的变更提案
/openspec:apply — 实现变更
/openspec:archive — 归档完成的变更

如果斜杠命令没出现，重启一下 Cursor。命令是启动时加载的。

使用 @ 引用规范文件

Cursor 的 @ 符号可以引用文件。和 OpenSpec 配合使用效果很好：

@openspec/project.md
@openspec/specs/auth/spec.md

请基于现有的认证规范，添加 OAuth 登录支持。

这样 AI 就能读到你的项目上下文和现有规范，减少误解。

Cursor Rules 配合 OpenSpec

在 .cursorrules 文件里加一条，让 Cursor 始终关注 OpenSpec 规范：

在进行任何功能开发前，先检查 openspec/specs/ 目录下是否有相关规范。
如果有，严格按照规范实现。
如果没有，先通过 OpenSpec 工作流创建变更提案。

这样即使你忘了，Cursor 也会提醒你先看规范。

常见问题和踩坑经验

在使用 OpenSpec 的过程中，开发者们踩过不少坑。这里总结几个常见的。

问题 1：AI 生成的规范太模糊

有时候你简单说一句"加个评论功能"，AI 生成的提案可能很泛泛而谈。解决方法是提供更具体的需求描述：

❌ 加个评论功能

✅ 添加文章评论功能：
- 登录用户可以对文章发表评论
- 评论支持纯文本，最多 500 字
- 用户可以编辑/删除自己的评论
- 评论按时间倒序显示，每页 20 条
- 评论需要审核才能公开显示

需求描述越具体，生成的规范越精确。

问题 2：变更冲突

如果你同时开了多个变更提案，它们可能会修改同一个规范文件，导致归档时冲突。

用 openspec list 查看当前所有活跃的变更：

openspec list

如果发现有重叠，要么合并变更，要么按顺序一个个完成再归档。尽量避免同时开太多变更。

问题 3：MODIFIED vs ADDED 用错

这是新手常犯的错误。

## ADDED Requirements：添加全新的功能，和现有功能没有直接关系
## MODIFIED Requirements：修改现有功能的行为

用 MODIFIED 时，要先复制完整的原始需求，再做修改。不能只写你改的部分，否则归档时会丢失信息。

问题 4：规范和代码脱节

用了一段时间后，可能出现代码改了但规范没更新的情况（尤其是紧急 bug 修复时）。

建议的做法是：任何代码修改都应该有对应的 OpenSpec 变更，哪怕是很小的改动。形成习惯后，规范就会和代码保持同步。

如果发现已经脱节，花时间做一次规范同步——让 AI 读代码、更新规范。磨刀不误砍柴工。

实用模板分享

最后分享几个我常用的模板，可以直接复制使用。

proposal.md 模板

# 变更提案：[功能名称]

## 变更 ID
[change-id]

## 摘要
[一句话描述这个变更做什么]

## 动机
为什么需要这个变更？解决什么问题？

## 变更范围
- [影响的模块 1]
- [影响的模块 2]
- [新增的功能点]

## 不在范围内
- [明确排除的内容]

## 技术约束
- [需要遵守的技术限制]

## 验收标准
- [ ] [具体可验证的条件 1]
- [ ] [具体可验证的条件 2]
- [ ] [具体可验证的条件 3]

## 相关链接
- [设计稿 URL]
- [相关 Issue]

tasks.md 模板

# 任务清单

## 预估工时
[总体预估]

## 1. [阶段名称，如"数据库变更"]
- [ ] 1.1 [具体任务]
- [ ] 1.2 [具体任务]

## 2. [阶段名称，如"后端开发"]
- [ ] 2.1 [具体任务]
- [ ] 2.2 [具体任务]
- [ ] 2.3 [具体任务]

## 3. [阶段名称，如"前端开发"]
- [ ] 3.1 [具体任务]
- [ ] 3.2 [具体任务]

## 4. 测试与文档
- [ ] 4.1 单元测试
- [ ] 4.2 集成测试
- [ ] 4.3 更新相关文档

## 注意事项
- [实现时需要注意的点]

spec.md delta 模板

# Delta for [模块名称]

## ADDED Requirements

### Requirement: [需求名称]
The system SHALL [需求描述，使用 SHALL/MUST 等关键词].

#### Scenario: [场景名称]
- GIVEN [前置条件]
- WHEN [触发动作]
- THEN [预期结果]

## MODIFIED Requirements

### Requirement: [原需求名称]
[完整复制原需求内容，然后修改相应部分]

## REMOVED Requirements

### Requirement: [被移除的需求名称]
[说明移除原因]

下一章是 MBRY 提示框架。学会用 OpenSpec 管理需求后，还需要知道怎么高效地和 AI 沟通。MBRY 是一个简洁的提示结构，让你每次和 AI 对话都能一击即中。