OpenSpec 入门指南：让AI告别“猜心式”编程，拥抱规范驱动开发在与 AI 编码助手（如 Cursor、Claud

1. 为什么需要 OpenSpec？

在与 AI 编码助手（如 Cursor、Claude Code、Qoder）协作时，你是否常遇到以下痛点：

需求“漂移”：对话历史一长，AI 就忘了最初的需求，开始“自由发挥”。
遗漏细节：口头沟通的需求，AI 经常遗漏边界条件或非功能性要求。
不可复现：上次还能运行的 Prompt，这次可能生成完全不同的代码。

OpenSpec 正是为了解决这些问题而生的轻量级框架。它的核心理念是 “规范先行”：在编写任何代码之前，先让人和 AI 就“要做什么”达成一份可审查、可落地的协议。

简单来说，OpenSpec 相当于给 AI 提供了结构化的 “施工蓝图” ，将模糊的闲聊式的开发模式转变为严谨的工程化流程。

2. 核心概念

目录结构与“两库分离”

OpenSpec 通过在项目添加一个 openspec/ 的根目录来管理工作流。其设计精髓在于 “真相源”与“变更提案”的物理分离。

openspec/
├── specs/           # 【真相源】当前系统已实现的“确定性”行为
│   └── [功能模块]/
│       └── spec.md
├── changes/         # 【工作区】待实现的“提议”变更
│   ├── [变更名称]/  # 例如：add-dark-mode
│   │   ├── proposal.md # 为什么要改？改什么？
│   │   ├── design.md   # 技术方案与决策
│   │   ├── tasks.md    # 实施清单（Checklist）
│   │   └── specs/      # 针对真相源的“增量补丁”
│   └── archive/     # 已完成的历史归档

specs/ 就像一个 “主干” ，记录了项目当前的真实全貌。现有项目接入的时候可让AI参考OpenSpec 规范追溯生成specs。
changes/ 则是 “分支” ，每一个变更都是独立的文件夹，包含了该变更的所有计划、设计和增量规范。这种方式让变更范围清晰可控，支持多人并行开发。

增量规范

增量规范是 OpenSpec 中的关键概念。它们显示了相对于当前规范发生了哪些变化。

3. 环境搭建与初始化

环境要求

Node.js 20.19.0 或更高版本。

安装 CLI 工具

# 安装官方版本
npm install -g @fission-ai/openspec@latest

# 或中文优化版
npm install -g @studyzy/openspec-cn

在项目中初始化

进入你的项目根目录，运行初始化命令：

cd your-project
openspec init   # 中文版使用 openspec-cn init

两种模式

默认快速路径（core配置文件）

/opsx:propose
/opsx:explore
/opsx:apply
/opsx:archive

典型流程：

/opsx:propose ──► /opsx:apply ──► /opsx:archive

初始化时，CLI 会询问你使用的 AI 工具（如 Cursor、Claude Code、Qoder）。选择后，它会在对应目录自动生成快捷命令（Slash Commands）和 Skills，让你在聊天框里就能驱动整个流程。

扩展/完整工作流程（自定义选择） 通过运行 openspec config profile 选择更多：/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive、/opsx:onboard。

openspec config profile

4. 核心工作流（三/四步法）

我们以官方的 demo + 快捷命令为例：为现有的 Web 应用增加深色模式（Dark Mode）。

第一步：探索需求

在 AI 对话框输入 /opsx:explore：

/opsx:explore add-dark-mode

AI 会了解现有架构，并把关键问题整理出来，和你一起探讨。消除所有不确定性后生成最终方案，由你决定是否进入 proposal 阶段。

如果需求已经特别明确的，可以跳过这一步，开启三步模式：

你：/opsx:propose add-dark-mode
AI：已创建 openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么要做这个，什么在变
     ✓ specs/       — 需求和场景
     ✓ design.md    — 技术方案
     ✓ tasks.md     — 实现清单
     准备好开始实现了！

你：/opsx:apply
AI：开始实现任务...
    ✓ 1.1 添加主题上下文 Provider
    ✓ 1.2 创建切换组件
    ✓ 2.1 添加 CSS 变量
    ✓ 2.2 接入 localStorage
    所有任务已完成！

你：/opsx:archive
AI：已归档至 openspec/changes/archive/2025-01-23-add-dark-mode/
    Specs 已更新。可以开始下一个功能了。

第二步：创建变更

在 AI 对话框输入 /opsx:propose：

/opsx:propose

AI 自动在 changes/ 目录下创建一个文件夹（如 add-dark-mode），并生成以下工件（Artifact）：

proposal.md：阐述动机、影响范围、验收标准 (MUST/SHOULD)。

# 提案：添加深色模式

## 意图
用户要求提供深色模式选项，以在夜间使用时减少眼睛疲劳并匹配系统偏好。

## 范围
包含：
- 设置中的主题切换
- 系统偏好检测
- 在 localStorage 中持久化偏好

不包含：
- 自定义颜色主题（未来工作）
- 每页主题覆盖

## 方法
使用 CSS 自定义属性进行主题化，配合 React context 进行状态管理。在首次加载时检测系统偏好，允许手动覆盖。

design.md：技术决策（例如使用 CSS 变量还是 CSS-in-JS？）、风险分析。

# 设计：添加深色模式

## 技术方法
通过 React Context 管理主题状态以避免属性传递。CSS 自定义属性支持运行时切换而无需类切换。

## 架构决策

### 决策：Context 优于 Redux
使用 React Context 管理主题状态的原因：
- 简单的二元状态（浅色/深色）
- 无复杂状态转换
- 避免添加 Redux 依赖

...

## 文件变更
- `src/contexts/ThemeContext.tsx`（新建）
- `src/components/ThemeToggle.tsx`（新建）
- `src/styles/globals.css`（修改）

tasks.md：具体的编码任务清单。

# 任务

## 1. 主题基础设施
- [ ] 1.1 创建具有浅色/深色状态的 ThemeContext
- [ ] 1.2 添加 CSS 自定义属性用于颜色
- [ ] 1.3 实现 localStorage 持久化
- [ ] 1.4 添加系统偏好检测

## 2. UI 组件
- [ ] 2.1 创建 ThemeToggle 组件
- [ ] 2.2 在设置页面添加切换器
- [ ] 2.3 更新 Header 包含快速切换

## 3. 样式
- [ ] 3.1 定义深色主题调色板
- [ ] 3.2 更新组件使用 CSS 变量
- [ ] 3.3 测试可访问性的对比度比率

specs/ui/spec.md：增量规范。

# UI 变更增量规范

## 新增需求

### 需求：主题选择
系统必须（SHALL）允许用户在浅色主题和深色主题之间进行选择。

#### 场景：手动切换
- **假设** 用户在任意页面上
- **当** 用户点击主题切换按钮
- **则** 界面主题立即切换
- **并且** 用户的选择偏好会在会话间持久保存

#### 场景：跟随系统偏好
- **假设** 用户没有保存过任何主题偏好
- **当** 应用加载时
- **则** 使用操作系统偏好的配色方案

Artifact 生成完成后，你可以先阅读 proposal.md 和 specs/<capability>/spec.md。如果发现 AI 理解还有偏差，直接修改 markdown 文件，或者在对话中纠正它。比如：

“请修改提案，Tag标签也需要适配深色模式。”

第三步：实施编码

一旦提案锁定，输入实施命令：

/opsx:apply

此时，AI 的行为被严格 “约束” 了。它不再自由发挥，而是严格依据 tasks.md 和 spec.md 中的场景来编写代码。每完成一项任务，它通常会在 tasks.md 中打勾 [x]。

第四步：归档与沉淀

当代码合并，功能上线后，执行归档：

/opsx:archive

AI 会将 changes/add-dark-mode/specs/ 中的增量修改合并回 specs/theme/spec.md 主目录，并将 add-dark-mode 文件夹移入 archive。从此，深色模式成为了项目的“既定事实”，未来的变更都将基于更新后的规范。

更多工作流示例参考

5. 核心命令速查表

当前命令的演示都是最基本的用法，很多命令都支持参数没有列出，完整命令参考（汉化）。

AI 对话斜杠命令 (Slash Commands)

命令	阶段	作用
`/opsx:explore`	探索	非正式讨论需求，不生成文件，仅对话
`/opsx:propose`	规划	创建变更文件夹，生成提案和设计草稿
`/opsx:apply`	实施	按照任务清单和规范编写代码
`/opsx:archive`	归档	完成变更，更新主规范，移入存档

终端 CLI 命令

命令	作用
`openspec list`	查看当前活跃的变更列表
`openspec show <change名>`	查看变更详情
`openspec validate <change名>`	校验规范格式是否正确
`openspec archive <id> --yes`	非交互式归档（CI/CD 中用）

扩展自定义

命令	作用
`/opsx:new`	启动新的变更，功能同`/opsx:propose`
`/opsx:continue`	显示有哪些可以继续处理的未完成的变更，重复使用此方法可以逐步构建更改。
`/opsx:ff`	一次性生成所有规划工件（`Artifact`），一般在`/opsx:new`之后执行
`/opsx:verify`	验证实现是否与工件一致
`/opsx:sync`	将增量规范同步到主规范
`/opsx:bulk-archive`	归档多个已完成的更改
`/opsx:onboard`	引导式完整变更流程教学

6. 项目配置

openspec/config.yaml 项目配置允许您设置默认值并将项目特定的上下文注入到所有工件中。

创建配置

配置可以在过程中创建openspec init，也可以手动创建：

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

配置字段

场地	类型	描述
`schema`	细绳	新变更的默认架构（例如，`spec-driven`）
`context`	细绳	项目上下文已注入到所有工件指令中
`rules`	目的	每个工件的规则，以工件 ID 为键

7. OpenSpec vs 其他工具

特性	OpenSpec	spec-kit	普通 Prompt 编程
核心优势	棕地项目优化、变更可追溯	绿地项目 (0→1) 强	快速原型
变更管理	独立文件夹，增量补丁清晰	结构较弱	依赖聊天记忆
协作性	规范即文档，可脱离对话审查	同上	无法审查，不可复现

OpenSpec 特别适合在现有复杂项目上进行迭代，尤其是当修改会波及多个模块时，它的“增量补丁”机制让范围蔓延得到控制。

8. 总结

OpenSpec 并不是要取代你的 IDE 或 Git，而是作为 AI 编码助手的“协议层” 存在。它通过将模糊的意图固化为清晰的 Markdown 规范，解决了 AI 编程最大的痛点——不确定性。

最佳实践建议：

从小处着手：不要试图全量改造，下次修 Bug 或加小功能时，尝试使用 OpenSpec 流程。
规范即代码：将 openspec/ 文件夹提交到 Git 仓库，这将成为团队的知识库和审计日志。