OpenSpec：基于规范驱动开发实战

使用 Cursor、Claude Code 或 GitHub Copilot 开发时，最令人头疼的往往不是 AI 写不出代码，而是它写得太快、改得太乱。在跨多个文件的现有（Brownfield）项目中，AI 极其容易在对话记录里遗忘上下文、无视既有架构甚至破坏原有逻辑。

为了解决“上下文随聊即忘”和“生成代码不可控”的问题，Fission-AI 推出了 OpenSpec —— 一个专为 AI 编码助手设计的规范驱动开发（Spec-Driven Development, SDD）轻量级框架。

核心机制：OpenSpec 是什么？

OpenSpec 不依赖任何复杂的 MCP 服务器或额外的 API Key，它纯粹基于 Git 仓库的文件系统，将项目的“需求规范”与“代码实现”强制解耦。

它引入了两个核心目录结构：

• openspec/specs/（单一事实源）：存储当前系统所有功能的最新规范文件（例如 auth/spec.md）。这是系统当下的“权威文档”。

• openspec/changes/（变更提案）：任何新功能或重构，都必须先在变更文件夹中生成 proposal.md（提案描述）、tasks.md（任务拆解）以及 spec deltas（规范变更增量）。

核心逻辑：在 AI 动任何一行代码之前，人类必须先审查并确认变更提案。

安装与配置

准备环境

• Node.js >= 20.19.0

1. 全局安装 CLI

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

2. 项目初始化

进入你的代码仓库根目录，执行初始化：

cd my-project
openspec init
​

初始化过程中，CLI 会让你选择正在使用的 AI 编码工具（如 Claude Code、Cursor、OpenCode 等）。OpenSpec 会自动生成项目根目录下的 AGENTS.md 引导文件，并为支持的工具注入 /opsx:* 斜杠指令（Slash Commands）。

标准工作流（4 步法）

[表达意图] ➔ [生成提案 & Spec Delta] ➔ [人类审查] ➔ [执行代码 & 归档]
​

1. 探索或提案 (/opsx:explore 或 /opsx:propose) 告知 AI 你想改动的功能，AI 会读取现有代码和 specs/，并在 openspec/changes/<change-id>/ 下生成变更文件。

2. 审查方案 (Review) 在编辑器中检查 tasks.md 里的任务拆解是否合理，确认 spec.md 增量补丁（GIVEN/WHEN/THEN）是否漏掉边缘条件。

3. 执行变更 (/opsx:apply) 确认方案无误后，指令 AI 开始写代码。AI 将逐项完成 tasks.md 中的 Checkbox，并标注完成状态。

4. 归档沉淀 (openspec archive) 实现并通过测试后，执行归档。本次变更的 spec deltas 会自动合并进主干 openspec/specs/ 中，作为未来的长期上下文。

实战演示：为现有 Auth 模块添加“记住我”功能

以一个已有的 Web 项目为例，我们需要为登录功能新增“记住我（Remember Me）”选项，保持 30 天登录态。

第一步：发起变更提案

在你的 AI 助手（如 Claude Code 或 Cursor）中输入：

/opsx:propose 为 Auth 模块添加 Remember Me 复选框，勾选后 Session 有效期延长至 30 天

AI 会检索现有的 openspec/specs/auth/spec.md 及后端 Session 处理逻辑，并创建变更目录 openspec/changes/add-remember-me/。

第二步：审查自动生成的 Spec Delta

打开生成的 openspec/changes/add-remember-me/specs/auth/spec.md，你会看到标准的规范 Patch 格式：

### Requirement: Session Expiration
​
#### Scenario: Default session timeout
- GIVEN a user has authenticated without checking "Remember me"
- WHEN 24 hours pass without activity
- THEN invalidate the session token
​
#### Scenario: Extended session with remember me
+ GIVEN user checks "Remember me" at login
+ WHEN 30 days have passed
+ THEN invalidate the session token
+ AND clear the persistent cookie
​

同目录下的 tasks.md 已经被拆解为具象的任务清单：

• 1. 数据库用户表/Session 表增加 remember_me 字段与过期时间设置

• 2. 修改前端 Login Form，添加 Remember Me 复选框并传递参数

• 3. 修改后端 Auth controller 逻辑，调整 Cookie 过期策略

如果你发现 AI 少考虑了安全问题，直接在 spec.md 中修改添加 - AND set SameSite=Strict flag，AI 会依据修正后的规范重新调整实现思路。

第三步：让 AI 执行代码修改

检查无误后，直接在 AI 窗口输入：

/opsx:apply add-remember-me

AI 会精准按照 tasks.md 的步骤修改 src/auth/session.ts 等目标文件，且不会越界去动无关的组件代码。

第四步：归档代码与规范

测试运行无误后，在终端执行：

openspec archive add-remember-me --yes

openspec/changes/add-remember-me/ 目录会被清理，最新的 30 天 Session 规范被永久合并至 openspec/specs/auth/spec.md。后续无论换哪个 AI 助手，只要读取 specs/，就能准确知道这个系统的鉴权行为。

选型建议

对于中大型项目，引入 OpenSpec 的本质是用极低的 Markdown 审查成本，换取 AI 在大型代码库中编写代码时的准确性与可预测性。