一、什么是 OpenSpec？
1.1 问题背景
你是否遇到过这样的情况：和 AI 编程助手聊了半天，需求越说越多，最后 AI 却"失忆"了——忘记之前的约定，代码写得乱七八糟？这是因为 AI 的上下文窗口有限，当对话越来越长，早期的重要信息就会被"遗忘"。
这就是 OpenSpec 要解决的问题。简单来说，OpenSpec 是一个规范驱动开发（Spec-Driven Development, SDD）工具，它让 AI 编程助手在写代码之前，先把需求、设计、任务都记录下来形成文档，这样即使对话变长，AI 也不会"忘记"该做什么。
1.2 核心理念
OpenSpec 的设计哲学非常简洁：
→ 灵活不僵化（fluid not rigid）
→ 迭代不瀑布（iterative not waterfall）
→ 简单不复杂（easy not complex）
→ 适用于存量项目（built for brownfield）
→ 从个人项目到企业都可扩展
1.3 工作原理
OpenSpec 通过在你的项目中创建一个 openspec/ 目录来管理所有规范文档：
openspec/
├── specs/ # 系统行为的真实来源
│ └── <领域>/
│ └── spec.md
├── changes/ # 待处理的变更
│ └── <变更名称>/
│ ├── proposal.md # 为什么做、做什么
│ ├── specs/ # 规格变更（增量）
│ ├── design.md # 技术设计
│ └── tasks.md # 实现任务清单
└── config.yaml # 项目配置（可选）
核心理解：
specs/是系统当前行为的"真相源"，记录了你的系统目前是如何工作的changes/是待处理的变更，每个变更都有独立的文件夹，包含完整的需求-设计-任务链条
二、安装指南
2.1 系统要求
重要：OpenSpec 需要 Node.js 20.19.0 或更高版本。
你可以通过以下命令检查 Node.js 版本：
node --version
如果版本过低，请先升级 Node.js。推荐使用 nvm（Node Version Manager）来管理 Node.js 版本：
# 安装最新 LTS 版本
nvm install 22
nvm use 22
2.2 全局安装
使用 npm 全局安装 OpenSpec：
npm install -g @fission-ai/openspec@latest
其他包管理器：
# 使用 pnpm
pnpm add -g @fission-ai/openspec@latest
# 使用 yarn
yarn global add @fission-ai/openspec@latest
# 使用 bun
bun add -g @fission-ai/openspec@latest
2.3 初始化项目
安装完成后，进入你的项目目录并初始化 OpenSpec：
cd your-project
openspec init
初始化过程中，OpenSpec 会：
- 创建
openspec/目录结构 - 生成 AI 编程助手所需的技能文件（如
.claude/skills/） - 可选地创建项目配置文件
openspec/config.yaml - 询问你的工具比如：claude code或者cursor，根据你的需求选择就好
2.4 配置项目（推荐）
在初始化时，你可以创建一个项目配置文件 openspec/config.yaml。这个文件可以设置默认值，并为所有文档注入项目特定的上下文信息：
# openspec/config.yaml
schema: spec-driven
context: |
技术栈: TypeScript, React, Node.js
API 规范: RESTful, JSON 响应
测试: Vitest 单元测试, Playwright 端到端测试
代码风格: ESLint + Prettier, 严格 TypeScript
rules:
proposal:
- 包含回滚计划
- 识别受影响的团队
specs:
- 使用 Given/When/Then 格式编写场景
design:
- 复杂流程需要包含时序图
这个配置文件的作用：
schema：设置新变更的默认工作流模式context：注入到所有文档中的项目背景信息，帮助 AI 理解你的项目约定rules：为特定类型的文档添加额外的规则要求
2.5 更新 OpenSpec
当有新版本发布时，升级方式如下：
# 升级包
npm install -g @fission-ai/openspec@latest
# 在每个项目中刷新 AI 指令
cd your-project
openspec update
openspec update 命令会重新生成 AI 指令文件，确保使用最新的斜杠命令。
三、命令详解
OpenSpec 提供两种工作流模式：核心模式（Core Profile） 和 扩展模式（Expanded Workflow） 。新安装默认使用核心模式。
3.1 核心模式命令（默认）
这是最简洁的工作流，包含四个核心命令：
| 命令 | 用途 |
|---|---|
/opsx:propose | 创建变更并生成规划文档 |
/opsx:explore | 探索想法、调查问题、明确需求 |
/opsx:apply | 实现任务清单中的任务 |
/opsx:archive | 归档已完成的变更 |
3.1.1 /opsx:propose — 创建变更
这是最常用的起始命令，它会一次性创建变更文件夹和所有规划文档。
语法：
/opsx:propose [变更名称或描述]
参数：
| 参数 | 必填 | 说明 |
|---|---|---|
变更名称或描述 | 否 | 短横线分隔的名称，或自然语言描述 |
工作流程：
- 创建
openspec/changes/<变更名称>/目录 - 生成规划文档（proposal.md、specs/、design.md、tasks.md）
- 等待执行
/opsx:apply
示例：
你: /opsx:propose add-dark-mode
AI: 创建了 openspec/changes/add-dark-mode/
✓ proposal.md — 为什么做、做什么
✓ specs/ui/spec.md — 需求和场景
✓ design.md — 技术方案
✓ tasks.md — 实现清单
准备开始实现！运行 /opsx:apply
3.1.2 /opsx:explore — 探索问题
当你需求不明确，或者需要先调查问题时使用。这个命令不会创建任何文档，只是一个自由的探索对话。
语法：
/opsx:explore [主题]
什么时候使用：
- 需求还不清晰
- 需要调查多个技术方案
- 想了解现有代码库的情况
- 做技术选型决策
示例：
你: /opsx:explore
AI: 你想探索什么？
你: 我们的移动端应用应该怎么处理用户认证？
AI: 让我调查一下你当前的认证设置...
[分析代码库]
我看到你的 Web 端使用的是基于会话的认证。
对于移动端，我们有三个主要选项：
1. JWT 令牌（无状态，支持离线）
2. OAuth2（需要第三方登录时使用）
3. 扩展现有会话（更简单，但需要联网）
你的 API 已经配置了 CORS。你对哪个方向感兴趣？
你: 我们用 JWT 吧。能开始一个变更吗？
AI: 准备好了。运行 /opsx:propose add-jwt-auth 开始。
3.1.3 /opsx:apply — 实现任务
根据 tasks.md 中的任务清单，逐项完成实现。
语法：
/opsx:apply [变更名称]
工作方式：
- 读取
tasks.md并识别未完成的任务 - 逐个实现任务
- 完成后用
[x]标记任务
示例：
你: /opsx:apply
AI: 正在实现 add-dark-mode...
读取 tasks.md:
- [ ] 1.1 创建 ThemeContext
- [ ] 1.2 添加 CSS 自定义属性
- [ ] 1.3 实现 localStorage 持久化
正在处理 1.1: 创建 ThemeContext...
[创建 src/context/ThemeContext.tsx]
✓ 1.1 完成
正在处理 1.2: 添加 CSS 自定义属性...
[更新 src/styles/globals.css]
✓ 1.2 完成
...
3.1.4 /opsx:archive — 归档变更
完成变更后进行归档，将变更移动到归档目录，并同步规格文档。
语法：
/opsx:archive [变更名称]
工作方式：
- 检查文档完整性
- 检查任务完成状态（未完成会警告）
- 提示是否同步增量规格（如果尚未同步）
- 将变更移动到
openspec/changes/archive/YYYY-MM-DD-<名称>/
示例：
你: /opsx:archive
AI: 正在归档 add-dark-mode...
文档状态:
✓ proposal.md 存在
✓ specs/ 存在
✓ design.md 存在
✓ tasks.md 存在（8/8 任务完成）
增量规格: 尚未同步到主规格
→ 是否现在同步？（推荐）
你: 是的
AI: ✓ 已同步规格到 openspec/specs/ui/spec.md
✓ 已移动到 openspec/changes/archive/2025-01-24-add-dark-mode/
变更已成功归档。
3.2 扩展模式命令
如果你需要更细粒度的控制，可以启用扩展工作流：
# 选择工作流配置
openspec config profile
# 更新项目配置
openspec update
扩展模式提供更多命令：
| 命令 | 用途 |
|---|---|
/opsx:new | 创建变更框架（仅创建目录和元数据） |
/opsx:continue | 创建下一个文档（逐步进行） |
/opsx:ff | 快进：一次性创建所有规划文档 |
/opsx:verify | 验证实现与文档是否一致 |
/opsx:sync | 手动同步增量规格 |
/opsx:bulk-archive | 批量归档多个变更 |
/opsx:onboard | 引导式教程（适合新用户） |
3.2.1 /opsx:new — 创建变更框架
只创建变更目录和元数据文件，不生成任何文档。适合需要完全自定义的用户。
语法：
/opsx:new [变更名称] [--schema <模式名称>]
示例：
你: /opsx:new add-dark-mode
AI: 创建了 openspec/changes/add-dark-mode/
模式: spec-driven
准备创建: proposal
使用 /opsx:continue 创建它，或 /opsx:ff 创建所有文档。
3.2.2 /opsx:continue — 逐步创建文档
根据依赖关系，创建下一个可创建的文档。每执行一次创建一个文档。
语法：
/opsx:continue [变更名称]
文档依赖关系：
proposal ──► specs ──► design ──► tasks ──► 实现
示例：
你: /opsx:continue
AI: 变更: add-dark-mode
文档状态:
✓ proposal (已完成)
◆ specs (可创建)
◆ design (可创建)
○ tasks (等待: specs)
正在创建 specs...
[读取 proposal.md，根据需求创建规格]
✓ 已创建 openspec/changes/add-dark-mode/specs/ui/spec.md
现在可创建: tasks
运行 /opsx:continue 创建下一个文档。
3.2.3 /opsx:ff — 快进创建
一次性创建所有规划文档，适合需求明确的情况。
语法：
/opsx:ff [变更名称]
示例：
你: /opsx:ff add-dark-mode
AI: 快进创建 add-dark-mode...
✓ 创建 proposal.md
✓ 创建 specs/ui/spec.md
✓ 创建 design.md
✓ 创建 tasks.md
所有规划文档已完成！
准备开始实现。运行 /opsx:apply 开始。
3.2.4 /opsx:verify — 验证实现
在归档前验证实现是否与文档一致，检查三个维度：
| 维度 | 检查内容 |
|---|---|
| 完整性 | 所有任务已完成、所有需求已实现、场景已覆盖 |
| 正确性 | 实现符合规格意图、边界情况已处理 |
| 一致性 | 设计决策反映在代码中、模式保持一致 |
示例：
你: /opsx:verify
AI: 正在验证 add-dark-mode...
完整性
✓ tasks.md 中的所有 8 个任务已勾选
✓ specs 中的所有需求有对应代码
⚠ 场景"系统偏好检测"没有测试覆盖
正确性
✓ 实现符合规格意图
✓ 边界情况已处理
✓ 错误状态符合规格定义
一致性
✓ 设计决策反映在代码结构中
✓ 命名约定与 design.md 一致
⚠ 设计提到"CSS 变量"但实现使用了 Tailwind 类
总结
─────────────────────────────
严重问题: 0
警告: 2
可归档: 是（有警告）
建议:
1. 为系统偏好检测添加测试
2. 更新 design.md 以反映 Tailwind 使用，或重构为使用 CSS 变量
3.2.5 /opsx:bulk-archive — 批量归档
当你同时处理多个变更时，可以批量归档。它会自动检测规格冲突并解决。
示例：
你: /opsx:bulk-archive
AI: 发现 3 个已完成的变更:
- add-dark-mode (8/8 任务完成)
- fix-login-bug (3/3 任务完成)
- update-footer (2/2 任务完成)
检查规格冲突...
⚠ add-dark-mode 和 update-footer 都涉及 specs/ui/
检查代码库以解决...
两个变更都已实现。将按时间顺序合并:
1. add-dark-mode (创建于 1月20日)
2. update-footer (创建于 1月22日)
归档所有 3 个变更吗？
你: 是的
AI: ✓ 已归档 add-dark-mode
✓ 已归档 fix-login-bug
✓ 已归档 update-footer
规格已合并: add-dark-mode → update-footer
3.2.6 /opsx:onboard — 引导式教程
适合新用户学习完整工作流的交互式教程，使用你的真实代码库进行操作。
示例：
你: /opsx:onboard
AI: 欢迎使用 OpenSpec！
我将带你完成整个工作流程，使用你的真实代码库。
我们会找到一些可以改进的小地方，创建一个正式的变更，
实现它，然后归档。
让我扫描你的代码库寻找机会...
[分析代码库]
我发现了几个可以处理的地方:
1. 为联系表单添加输入验证
2. 改善认证流程中的错误消息
3. 为异步按钮添加加载状态
你对哪个感兴趣？（或者建议其他内容）
3.3 不同 AI 工具的命令语法
不同 AI 编程助手使用略微不同的命令语法：
| 工具 | 语法示例 |
|---|---|
| Claude Code | /opsx:propose, /opsx:apply |
| Cursor | /opsx-propose, /opsx-apply |
| Windsurf | /opsx-propose, /opsx-apply |
| GitHub Copilot (IDE) | /opsx-propose, /opsx-apply |
| Trae | 基于技能的调用，如 /openspec-propose |
四、注意事项
4.1 什么时候使用 OpenSpec
推荐使用：
- 新功能开发：当你需要添加一个完整的新功能时，OpenSpec 可以帮助你系统地规划需求、设计和任务。
- 复杂重构：涉及多个模块的重构工作，提前规划可以避免遗漏。
- 团队协作：当多人协作时，OpenSpec 的文档可以作为沟通的基础。
- 需要追踪历史：归档的变更提供了完整的决策记录和实现历史。
- AI 辅助开发：使用 AI 编程助手时，OpenSpec 可以防止 AI"遗忘"需求。
不推荐使用：
- 快速原型：如果你只是在验证一个想法，可能不需要完整的规格流程。
- 简单的 Bug 修复：一行代码的修复可能不需要完整的变更流程。
- 紧急修复：生产环境紧急修复时，先修复问题，之后可以补充文档。
- 实验性代码：不确定是否保留的实验性代码。
4.2 关键问题：紧急修改功能代码后，是否需要 /opsx:archive？
这是一个常见的问题。让我们分情况讨论：
情况一：修改的是当前正在进行的变更
如果你正在实现一个变更（已经运行了 /opsx:propose 但还没 /opsx:archive），在实现过程中发现需要紧急修改某些功能代码：
- 不需要 立即归档
- 应该 更新相关的文档（如
design.md或tasks.md）以反映变化 - 继续执行
/opsx:apply直到所有任务完成 - 最后执行
/opsx:archive完成归档
OpenSpec 的设计理念是"流畅迭代"——你可以在任何时候更新文档，不需要严格的阶段门控。
情况二：修改的是已归档的旧功能
如果你需要修改一个已经归档的功能：
- 应该 创建一个新的变更（
/opsx:propose fix-xxx） - 在新变更中说明修改的原因和范围
- 完成后正常归档
情况三：真正的紧急情况
对于生产环境的紧急修复：
- 先修复问题——不要让流程阻碍紧急响应
- 事后补充：如果修改较大，可以创建一个"追溯性"的变更文档记录决策
- 更新主规格：确保
specs/反映新的系统行为
核心原则：
/opsx:archive的目的是将增量规格合并到主规格中。如果你修改了系统行为但没有归档，specs/就不会反映真实的系统状态。所以，只要系统行为发生了变化，最终都应该归档——但时机可以灵活选择。
4.3 常见问题及解决方案
问题 1："Change not found"
原因：命令无法识别要操作的变更。
解决方案：
- 明确指定变更名称：
/opsx:apply add-dark-mode - 检查变更文件夹是否存在：运行
openspec list - 确认你在正确的项目目录
问题 2：命令不被识别
原因：AI 工具没有识别 OpenSpec 命令。
解决方案：
- 确保已初始化：
openspec init - 重新生成技能文件：
openspec update - 检查
.claude/skills/目录是否存在 - 重启 AI 工具以加载新技能
问题 3：文档生成不完整或不正确
原因：AI 创建的文档质量不佳。
解决方案：
- 在
openspec/config.yaml中添加更多项目上下文 - 为特定文档类型添加规则
- 在变更描述中提供更多细节
- 使用
/opsx:continue代替/opsx:ff以获得更多控制
问题 4：多变更并行时的规格冲突
原因：多个变更修改了同一份规格。
解决方案：
- 使用
/opsx:bulk-archive，它会自动检测和解决冲突 - 手动使用
/opsx:sync在归档前同步规格 - 检查冲突后按时间顺序合并
问题 5：AI 模型选择
建议：OpenSpec 与高推理能力的模型配合效果最好。推荐使用：
- Claude Opus 4.5
- GPT-5.2
这些模型在规划和实现阶段都能提供更好的结果。
问题 6：上下文窗口管理
建议：OpenSpec 在干净的上下文窗口中效果最好。建议：
- 开始实现前清除上下文
- 在整个会话中保持良好的上下文管理
- 定期使用
openspec status检查状态
4.4 模型选择与上下文管理最佳实践
模型选择：
- OpenSpec 与高推理能力模型配合效果最佳
- 推荐使用 Opus 4.5 和 GPT 5.2 进行规划和实现
上下文管理：
- OpenSpec 受益于干净的上下文窗口
- 在开始实现前清除上下文
- 在会话中保持良好的上下文卫生
五、实战案例：为网站添加主题切换功能
下面我们通过一个完整的实战案例，演示如何使用 OpenSpec 为网站添加一个主题切换功能。
5.1 场景描述
假设我们有一个 Next.js 网站，用户反馈希望在夜间使用时能够切换到深色主题，减少眼睛疲劳。我们需要：
- 添加浅色/深色主题切换
- 支持系统偏好检测
- 持久化用户选择
5.2 步骤一：探索需求（可选）
如果对需求还有疑问，可以先探索：
你: /opsx:explore
AI: 你想探索什么？
你: 我想给网站添加深色模式，但不确定该怎么实现。我们的技术栈是 Next.js + Tailwind CSS。
AI: 让我调查一下你的项目...
[分析项目结构、现有样式系统]
我发现你已经在使用 Tailwind CSS，它内置了深色模式支持。有几个实现选项：
选项 1: 使用 Tailwind 的 class 策略
- 在 html 元素添加 dark 类
- 使用 dark: 前缀定义深色样式
- 简单，与现有技术栈无缝集成
选项 2: 使用 CSS 变量
- 定义 --color-* 变量
- 根据主题切换变量值
- 更灵活，支持自定义主题
选项 3: 使用 next-themes 库
- 专为 Next.js 设计
- 自动处理 SSR 和系统偏好
- 开箱即用，但增加依赖
考虑到你的技术栈，选项 1 或 3 都很合适。你的偏好是什么？
你: 我们用 Tailwind 的 class 策略吧，不想增加新依赖。
AI: 好选择！准备好开始了吗？运行 /opsx:propose add-theme-toggle 开始。
5.3 步骤二：创建变更
使用核心命令快速创建变更：
你: /opsx:propose add-theme-toggle
AI: 创建了 openspec/changes/add-theme-toggle/
✓ proposal.md — 为什么做、做什么
✓ specs/ui/spec.md — 需求和场景
✓ design.md — 技术方案
✓ tasks.md — 实现清单
准备开始实现！运行 /opsx:apply
5.4 步骤三：查看生成的文档
让我们看看生成了什么文档。这些文档可以帮助我们理解 AI 的规划是否正确。
proposal.md（部分内容）：
# Proposal: Add Theme Toggle
## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage and improve overall user experience.
## Scope
- Add theme toggle in header
- Support system preference detection
- Persist preference in localStorage
- Apply theme using Tailwind's dark mode (class strategy)
## Approach
Use Tailwind's built-in dark mode with `class` strategy.
A React context will manage theme state, and a toggle
component will be added to the header.
tasks.md（部分内容）：
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add theme detection for system preference
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add class toggle on html element
## 2. UI Components
- [ ] 2.1 Create ThemeToggle component with sun/moon icons
- [ ] 2.2 Add toggle to Header component
- [ ] 2.3 Add smooth transition animation
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update existing components with dark: variants
- [ ] 3.3 Update global styles for dark mode
5.5 步骤四：实现任务
确认文档无误后，开始实现：
你: /opsx:apply
AI: 正在实现 add-theme-toggle...
读取 tasks.md:
- [ ] 1.1 Create ThemeContext
- [ ] 1.2 Add theme detection
- [ ] 1.3 Implement localStorage persistence
...
正在处理 1.1: Create ThemeContext...
[创建 src/contexts/ThemeContext.tsx]
✓ 1.1 完成
正在处理 1.2: Add theme detection...
[更新 ThemeContext，添加系统偏好检测]
✓ 1.2 完成
...
[继续实现所有任务]
✓ 所有任务完成！
5.6 步骤五：实现中发现问题（演示流畅迭代）
假设在实现过程中，我们发现需要在设置页面也添加一个主题切换入口：
你: 等等，我还需要在设置页面也添加一个主题切换选项
AI: 好的，让我更新 tasks.md 添加这个任务...
[更新 tasks.md，添加新任务]
新增任务:
- [ ] 2.4 Add theme settings section in Settings page
继续实现吗？
你: /opsx:apply
AI: 继续实现 add-theme-toggle...
正在处理 2.4: Add theme settings section...
[创建设置页面的主题区域]
✓ 2.4 完成
这就是 OpenSpec 的"流畅迭代"——你可以在任何时候更新文档，不需要重新开始。
5.7 步骤六：验证实现（扩展模式）
如果你启用了扩展模式，可以在归档前验证：
你: /opsx:verify
AI: 正在验证 add-theme-toggle...
完整性
✓ 所有任务已完成
✓ 所有需求有对应代码
✓ 所有场景已覆盖
正确性
✓ 实现符合规格意图
✓ 边界情况（无 localStorage、系统偏好变化）已处理
一致性
✓ 使用 Tailwind class 策略符合设计
✓ 组件命名与设计文档一致
总结
─────────────────────────────
严重问题: 0
警告: 0
可归档: 是
5.8 步骤七：归档变更
完成并验证后，归档变更：
你: /opsx:archive
AI: 正在归档 add-theme-toggle...
文档状态:
✓ proposal.md 存在
✓ specs/ui/spec.md 存在
✓ design.md 存在
✓ tasks.md 存在（9/9 任务完成）
增量规格: 尚未同步到主规格
→ 是否现在同步？
你: 是的
AI: ✓ 已同步规格到 openspec/specs/ui/spec.md
✓ 已移动到 openspec/changes/archive/2025-01-24-add-theme-toggle/
变更已成功归档。准备下一个功能！
5.9 案例总结
通过这个实战案例，我们演示了：
- 探索阶段：使用
/opsx:explore调查技术方案 - 创建变更：使用
/opsx:propose快速创建完整规划 - 实现任务：使用
/opsx:apply逐项完成任务 - 流畅迭代：在实现过程中动态更新文档
- 验证实现：使用
/opsx:verify确保质量 - 归档变更：使用
/opsx:archive完成流程
六、CLI 命令参考
除了在 AI 编程助手中使用的斜杠命令，OpenSpec 还提供了 CLI 命令用于管理和验证：
# 查看活跃变更
openspec list
# 查看变更详情
openspec show <变更名称>
# 验证规格格式
openspec validate <变更名称>
# 交互式仪表板
openspec view
# 查看变更状态
openspec status --change <变更名称>
# 列出可用模式
openspec schemas
# 创建新模式
openspec schema init <模式名称>
# 从现有模式派生
openspec schema fork spec-driven my-workflow
# 验证模式结构
openspec schema validate <模式名称>
七、总结
OpenSpec 是一个简洁而强大的工具，它通过以下方式改善 AI 辅助开发体验：
- 防止遗忘：将需求、设计、任务文档化，避免 AI 上下文溢出
- 流畅迭代：没有严格的阶段限制，随时可以更新文档
- 历史追踪：归档的变更提供完整的决策和实现记录
- 团队协作：文档作为沟通基础，提高协作效率
- 灵活定制：支持自定义模式和工作流
核心工作流：
/opsx:propose ──► /opsx:apply ──► /opsx:archive
就这么简单！如果你需要更多控制，可以启用扩展模式，获得逐步创建文档、验证实现等高级功能。
获取帮助：
- GitHub Issues: github.com/Fission-AI/…
- Discord: discord.gg/YctCnvvshC
- Twitter: @0xTab
本文档基于 OpenSpec 1.2.0 版本编写。
