OpenSpec 规范驱动开发完全教程

从零开始，掌握 AI 原生规范驱动开发工具 OpenSpec

1. 什么是 OpenSpec？
2. 核心设计理念
3. 与同类工具对比
4. 环境准备与安装
5. 项目初始化与配置
6. 核心概念详解
7. 核心工作流：三大步完成开发
8. 扩展工作流：精细控制每一步
9. 四大产物详解
10. 项目目录结构
11. CLI 命令参考手册
12. 配置系统详解
13. Schema 自定义工作流
14. 支持的 AI 工具与命令格式
15. 完整实战案例：为应用添加暗黑模式
16. 多场景工作流模式
17. 最佳实践
18. 常见问题与解决方案
19. 总结

1. 什么是 OpenSpec？

OpenSpec 是一个 AI 原生的规范驱动开发（Spec-Driven Development）系统，由 Fission AI 开发并开源（MIT 协议）。

它的核心使命很简单：在写第一行代码之前，先让人类和 AI 对"要做什么"达成一致。

一句话概括

OpenSpec 为 AI 编码助手提供一个轻量级规范层，让开发过程更可预测、更高效。

解决什么问题？

当你直接让 AI 写代码时，常常会遇到：

问题	描述
需求模糊	只有一句话的描述，AI 猜测你的意图
方向偏离	AI 生成的代码和你想要的南辕北辙
无法追溯	需求只存在于聊天记录中，无法回溯
重复劳动	需求变更后，要手动修改多处代码
团队混乱	多人协作时，AI 的产出风格不一致

OpenSpec 通过引入结构化的规范流程，系统性地解决了这些问题。

2. 核心设计理念

OpenSpec 的设计遵循五大原则：

原则一：流动而非僵化（Flow, not rigidity）

不会强制你走固定的阶段关卡。你可以随时更新任何产物，甚至跳过某些步骤。规范是帮你思考的工具，不是束缚你的枷锁。

原则二：迭代而非瀑布（Iterative, not waterfall）

不是一次性从需求到代码的瀑布流，而是可以反复迭代、随时调整的增量过程。先写个大概，再逐步完善。

原则三：简单而非复杂（Simple, not complex）

核心工作流只有三步：Propose → Apply → Archive。没有复杂的概念和流程，上手即用。

原则四：存量项目优先（Existing projects first）

不是只适合从零开始的新项目，已有项目也可以无缝引入 OpenSpec。你不需要重写任何代码。

原则五：从个人项目扩展到企业级（Scale from personal to enterprise）

一个人用很轻量，团队用也能协作。从个人开发者到企业团队，同一个工具，不同的深度。

3. 与同类工具对比

对比项	OpenSpec	Spec Kit (GitHub)	无规范（直接让 AI 写代码）
定位	轻量级规范驱动开发	重量级规范驱动开发	无规范
工作流	灵活，可自由迭代	严格阶段关卡	无
核心步骤	3 步（Propose → Apply → Archive）	5 步（Constitution → Specify → Plan → Tasks → Implement）	无
运行时依赖	Node 20+	Python 3.11+	无
AI 工具支持	20+	10+	无限制
灵活性	高——可随时更新任何产物	中——按阶段顺序推进	高——但不可控
学习曲线	低	中	无
适合场景	新项目 + 已有项目	新项目为主	快速原型

选择建议：

如果你追求简单灵活，选 OpenSpec
如果你需要严格的阶段管理，选 Spec Kit
如果你只是做个一次性原型，可以不用任何规范工具

4. 环境准备与安装

4.1 系统要求

要求	说明
Node.js	>= 20
AI 编程助手	Claude Code、Cursor、Windsurf、GitHub Copilot 等（至少一个）
Git	用于版本控制
GitHub CLI（可选）	用于提交反馈（`gh` 命令）

4.2 安装 OpenSpec CLI

使用 npm 全局安装：

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

安装完成后，验证：

openspec --version

4.3 更新 OpenSpec

npm update -g @fission-ai/openspec

# 更新后需要刷新项目中的指令文件
openspec update

5. 项目初始化与配置

5.1 交互式初始化

在项目根目录运行：

openspec init

初始化过程中会提示你：

选择要配置的 AI 工具（如 Claude、Cursor、Copilot 等）
选择工作流配置

完成后会创建以下目录结构：

openspec/
├── specs/              # 规范文档（源头真相）
├── changes/            # 变更目录
└── config.yaml         # 项目配置

.claude/skills/         # Claude Code 技能文件（如果选择了 claude）
.cursor/skills/         # Cursor 技能文件（如果选择了 cursor）

5.2 非交互式初始化

如果你不想一步步选，可以直接指定参数：

# 为 Claude 和 Cursor 配置
openspec init --tools claude,cursor

# 为所有支持的 AI 工具配置
openspec init --tools all

# 在指定目录初始化
openspec init ./my-project --tools claude

5.3 切换配置档案

默认情况下，OpenSpec 只启用 4 个核心命令（explore、apply、archive 等）。要解锁全部 11 个命令，需要切换到扩展档案：

# 切换到扩展档案（解锁全部命令）
openspec config profile

# 在交互式向导中选择 "Expanded Profile"

然后刷新配置：

openspec update

重要：切换配置后需要重启 AI 编辑器（如 Cursor、VS Code），斜杠命令才会生效。

5.4 支持的 AI 工具 ID

初始化时可以使用的工具 ID：

类别	工具 ID
主流编辑器	`cursor`, `claude`, `windsurf`, `github-copilot`, `codex`
国内工具	`qwen`, `codebuddy`, `lingma`, `trae`, `kimi`, `opencode`
其他工具	`auggie`, `cline`, `gemini`, `kilocode`, `roocode`, `crush`, `forgecode` 等

6. 核心概念详解

6.1 变更（Change）

变更是 OpenSpec 的核心工作单元。一个变更对应一个需求或功能。每个变更都有自己的目录，存放在 openspec/changes/ 下。

例如，添加暗黑模式就是一个变更：

openspec/changes/add-dark-mode/
├── proposal.md    — 为什么做 & 做什么
├── specs/         — 需求 & 验收场景
├── design.md      — 技术实现方案
└── tasks.md       — 实现任务清单

6.2 产物（Artifact）

每个变更会产生四类产物：

产物	文件	作用
提案（Proposal）	`proposal.md`	背景、目标、验收标准
规范（Specs）	`specs/`	详细需求、接口设计、UI 约定
设计（Design）	`design.md`	技术设计、模块划分、关键算法
任务（Tasks）	`tasks.md`	可执行的任务清单（带复选框）

6.3 Delta 规范

当一个变更修改了已有规范时，它使用增量规范（Delta Specs）来记录变化——只记录新增、删除、修改的部分，而不是重写整个规范文档。

归档时，Delta 规范会合并到主规范目录 openspec/specs/ 中。

6.4 归档（Archive）

完成的变更会被移动到归档目录，按日期组织：

openspec/changes/archive/2026-03-10-add-dark-mode/

归档确保所有产物保留为审计记录，同时主工作区保持干净。

7. 核心工作流：三大步完成开发

OpenSpec 的核心工作流只有三步，简单高效：

Propose（提案） → Apply（执行） → Archive（归档）

7.1 提案 — Propose

命令：/opsx:propose

做什么：一步创建变更目录和所有规划产物（proposal、specs、design、tasks）。

用法：

/opsx:propose add-dark-mode

或者用自然语言描述：

/opsx:propose 添加暗黑模式支持，用户可以切换深色/浅色主题

AI 的输出：

Created openspec/changes/add-dark-mode/
  ✓ proposal.md — 为什么做 & 做什么
  ✓ specs/ui/spec.md — 需求 & 验收场景
  ✓ design.md — 技术实现方案
  ✓ tasks.md — 实现任务清单
  Ready for implementation. Run /opsx:apply.

适用场景：需求清晰、变更范围明确时，这是最快的方式。

7.2 执行 — Apply

命令：/opsx:apply

做什么：AI 读取 tasks.md，逐个执行未完成的任务，写代码、创建文件、运行测试。

用法：

/opsx:apply

如果有多个进行中的变更，可以指定名称：

/opsx:apply add-dark-mode

AI 的执行过程：

Implementing add-dark-mode...
  Reading tasks.md:
  - [ ] 1.1 创建主题上下文 Provider
  - [ ] 1.2 创建主题切换组件
  - [ ] 2.1 添加 CSS 变量
  - [ ] 2.2 集成 localStorage 持久化

  ✓ 1.1 创建主题上下文 Provider
  ✓ 1.2 创建主题切换组件
  ✓ 2.1 添加 CSS 变量
  ✓ 2.2 集成 localStorage 持久化
  All tasks complete!

关键特性：

每完成一个任务，自动在 tasks.md 中标记 [x]
中断后可以恢复执行
你可以随时修改 tasks.md 再继续

7.3 归档 — Archive

命令：/opsx:archive

做什么：将完成的变更归档，合并 Delta 规范到主规范库。

用法：

/opsx:archive

AI 的执行过程：

Checking change: add-dark-mode
  Delta specs: Not yet synced → Sync now? (recommended)
  → Yes
  ✓ Synced specs to openspec/specs/ui/spec.md
  ✓ Moved to openspec/changes/archive/2026-03-10-add-dark-mode/
  Change archived successfully.

归档会做什么：

验证变更的产物和任务完成状态
提示同步 Delta 规范（如果还没同步）
将变更目录移到 archive/ 目录下
更新 CHANGELOG.md

8. 扩展工作流：精细控制每一步

当你需要更多控制时，可以使用扩展工作流。首先确保已切换到 Expanded Profile。

8.1 探索 — Explore

命令：/opsx:explore

做什么：与 AI 进行纯对话式探索——分析需求、研究技术方案、识别风险。不会创建任何文件，AI 进入只读模式。

用法：

/opsx:explore

或指定探索主题：

/opsx:explore 移动端认证方案

交互示例：

You: /opsx:explore
AI: 你想探索什么？
You: 我们应该用 JWT 还是 Session 做认证？
AI: [分析代码库，呈现 3 种方案的优缺点对比]
     方案 A: JWT — 优点：无状态...缺点：...
     方案 B: Session — 优点：...缺点：...
     方案 C: OAuth2 — 优点：...缺点：...

适用场景：需求模糊、技术选型不确定、头脑风暴时使用。

8.2 新建变更 — New

命令：/opsx:new

做什么：只创建变更目录和元数据文件（.openspec.yaml），不生成任何规划产物。

用法：

/opsx:new add-dark-mode

输出：

Created openspec/changes/add-dark-mode/
Schema: spec-driven
Ready to create: proposal
Use /opsx:continue to create it, or /opsx:ff to create all artifacts.

适用场景：你想先创建变更框架，再逐步填充内容。

8.3 逐步推进 — Continue

命令：/opsx:continue

做什么：查询当前产物依赖关系，只生成下一个缺失的产物。每次只生成一个，让你可以审查和修改后再继续。

用法：

/opsx:continue

交互示例：

You: /opsx:continue
AI: Change: add-dark-mode
    Artifact status:
    ✓ proposal    (已完成)
    ◆ specs       (可生成)
    ○ design      (阻塞 - 依赖: specs)
    ○ tasks      (阻塞 - 依赖: design)

    [生成 specs 后]
    ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md
    Now available: design

产物生成顺序：proposal.md → specs/ → design.md → tasks.md

适用场景：复杂变更，需要逐步审查每个产物。

8.4 快进模式 — FF

命令：/opsx:ff

做什么：一次性生成所有规划产物，按依赖顺序依次创建。相当于 /opsx:propose，但基于 /opsx:new 的脚手架。

用法：

/opsx:ff

输出：

Fast-forwarding add-dark-mode...
  ✓ Creating proposal.md
  ✓ Creating specs/ui/spec.md
  ✓ Creating design.md
  ✓ Creating tasks.md
  All planning artifacts complete!

适用场景：需求清晰、变更范围不大、有经验的开发者。

8.5 验证 — Verify

命令：/opsx:verify

做什么：验证代码实现是否与规范、设计文档一致。生成验证报告。

用法：

/opsx:verify

验证三个维度：

维度	关注点
完整性（Completeness）	所有任务是否完成、需求是否满足、场景是否覆盖
正确性（Correctness）	实现是否符合规范意图、边界情况是否处理
一致性（Consistency）	代码是否反映设计决策、编码模式是否统一

问题分类：

级别	含义
CRITICAL	严重问题——必须修复
WARNING	警告——建议修复
SUGGESTION	建议——可以改进

适用场景：在归档之前运行，发现代码与规范之间的"漂移"。

8.6 同步 — Sync

命令：/opsx:sync

做什么：将变更中的 Delta 规范合并到主规范目录 openspec/specs/。变更保持活跃状态（不会被归档）。

用法：

/opsx:sync

什么时候手动同步：

开发长周期变更，其他变更需要最新的主规范
多个并行变更需要看到彼此的规范更新
想单独预览合并效果

注意：归档时会自动提示同步，大多数情况下不需要手动运行。

8.7 批量归档 — Bulk Archive

命令：/opsx:bulk-archive

做什么：列出所有已完成的变更，支持多选批量归档。自动检测跨变更的规范冲突。

用法：

/opsx:bulk-archive

交互示例：

You: /opsx:bulk-archive
AI: Found 3 completed changes:
    [1] add-dark-mode (4/4 tasks done)
    [2] update-footer (3/3 tasks done)
    [3] fix-login-bug (2/2 tasks done)

    Checking for spec conflicts...
    ⚠ add-dark-mode and update-footer both touch specs/ui/
    [按时间顺序合并解决冲突]

适用场景：团队协作、多个并行变更同时完成时。

8.8 入门引导 — Onboard

命令：/opsx:onboard

做什么：基于你的真实代码库进行交互式教程，带你走完 OpenSpec 的完整工作流。

用法：

/opsx:onboard

特点：

基于你的真实项目，不是玩具示例
约 15-30 分钟完成
会生成真实的变更和代码（可以保留或删除）

适用场景：OpenSpec 新手必做！ 比读文档更实用。

9. 四大产物详解

每个变更包含四类产物，按依赖顺序生成：

9.1 提案（proposal.md）

核心问题：为什么要做这个变更？做什么？怎么判断做完了？

# Proposal: 添加暗黑模式

## 背景
用户在夜间使用应用时，白色背景刺眼，体验不佳。
竞品已普遍支持暗黑模式。

## 目标
- 支持深色/浅色主题切换
- 主题偏好持久化到 localStorage
- 所有页面适配暗黑模式

## 验收标准
- [ ] 用户可以通过切换按钮切换主题
- [ ] 刷新页面后主题偏好保持
- [ ] 所有组件在暗黑模式下显示正确

9.2 规范（specs/）

核心问题：具体需求是什么？有哪些验收场景？

# UI 规范: 暗黑模式

## 需求
- REQ-001: 系统必须提供主题切换按钮
- REQ-002: 主题切换必须即时生效，无需刷新
- REQ-003: 主题偏好必须持久化

## 验收场景
- 场景 1: 用户点击切换按钮 → 主题即时切换
- 场景 2: 用户刷新页面 → 主题保持上次选择
- 场景 3: 系统首次加载 → 跟随系统偏好

9.3 设计（design.md）

核心问题：技术层面怎么实现？模块怎么划分？

# 技术设计: 暗黑模式

## 架构决策
- 使用 React Context 管理主题状态
- CSS 变量实现主题切换
- localStorage 持久化偏好

## 模块划分
1. ThemeContext — 主题状态管理
2. ThemeToggle — 切换按钮组件
3. CSS Variables — 主题色值定义

## 关键接口
- useTheme() → { theme, toggleTheme }
- localStorage key: "app-theme"

9.4 任务（tasks.md）

核心问题：具体要做哪些事？按什么顺序？

# 任务清单: 暗黑模式

## 1. 基础设施
- [ ] 1.1 创建 ThemeContext Provider
- [ ] 1.2 定义 CSS 变量（深色/浅色）

## 2. UI 组件
- [ ] 2.1 创建 ThemeToggle 切换按钮
- [ ] 2.2 集成 localStorage 持久化

## 3. 全局适配
- [ ] 3.1 所有组件适配暗黑模式
- [ ] 3.2 添加系统偏好检测（prefers-color-scheme）

## 4. 测试
- [ ] 4.1 主题切换功能测试
- [ ] 4.2 持久化功能测试

10. 项目目录结构

完整目录结构

project/
├── openspec/
│   ├── specs/                          # 主规范库（源头真相）
│   │   ├── ui/
│   │   │   └── spec.md                 # UI 相关规范
│   │   ├── api/
│   │   │   └── spec.md                 # API 相关规范
│   │   └── data-model/
│   │       └── spec.md                 # 数据模型规范
│   ├── changes/                        # 变更目录
│   │   ├── add-dark-mode/             # 活跃变更
│   │   │   ├── .openspec.yaml          # 变更元数据
│   │   │   ├── proposal.md             # 提案
│   │   │   ├── specs/                  # Delta 规范
│   │   │   │   └── ui/
│   │   │   │       └── spec.md
│   │   │   ├── design.md              # 技术设计
│   │   │   └── tasks.md               # 任务清单
│   │   ├── fix-login-bug/             # 另一个活跃变更
│   │   └── archive/                    # 归档目录
│   │       ├── 2026-03-10-add-dark-mode/
│   │       └── 2026-03-12-update-footer/
│   ├── schemas/                        # 自定义工作流 Schema
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── config.yaml                     # 项目配置
├── src/                                # 源代码
├── .claude/                            # Claude Code 配置（如选择）
│   └── skills/
└── .cursor/                            # Cursor 配置（如选择）
    ├── skills/
    └── commands/

关键目录说明

目录	说明
`openspec/specs/`	主规范库——所有已确认的规范文档
`openspec/changes/`	活跃变更——正在开发的功能
`openspec/changes/archive/`	归档变更——已完成的变更记录
`openspec/schemas/`	自定义工作流 Schema
`openspec/config.yaml`	项目级配置

11. CLI 命令参考手册

11.1 初始化与更新

命令	说明
`openspec init`	初始化 OpenSpec
`openspec init --tools claude,cursor`	指定 AI 工具
`openspec init --tools all`	配置所有 AI 工具
`openspec init --force`	跳过提示，自动清理
`openspec update`	更新指令文件

11.2 浏览与查看

命令	说明
`openspec list`	列出活跃变更
`openspec list --specs`	列出规范
`openspec list --json`	JSON 输出（脚本用）
`openspec show <name>`	查看变更/规范详情
`openspec view`	交互式仪表盘

11.3 验证

命令	说明
`openspec validate`	验证结构问题
`openspec validate --all`	验证所有变更和规范
`openspec validate --strict`	严格模式
`openspec validate --all --json`	JSON 输出（CI 用）

11.4 生命周期

命令	说明
`openspec archive <name>`	归档变更
`openspec archive <name> --yes`	跳过确认提示
`openspec archive <name> --skip-specs`	跳过规范同步（工具/文档变更用）

11.5 工作流

命令	说明
`openspec status`	查看变更产物完成状态
`openspec status --change <name> --json`	JSON 输出
`openspec instructions`	获取产物创建指引
`openspec instructions design --change <name>`	获取特定产物指引
`openspec instructions apply --change <name>`	获取实现指引
`openspec templates`	查看模板路径
`openspec schemas`	列出可用的 Schema

11.6 Schema 管理

命令	说明
`openspec schema init <name>`	创建自定义 Schema
`openspec schema fork <source> <name>`	基于已有 Schema 创建副本
`openspec schema validate <name>`	验证 Schema 结构
`openspec schema which <name>`	查看 Schema 解析路径

11.7 配置

命令	说明
`openspec config list`	查看所有配置
`openspec config get <key>`	获取配置值
`openspec config set <key> <value>`	设置配置值
`openspec config profile`	配置工作流档案
`openspec config reset`	重置配置
`openspec config edit`	编辑器中打开配置

11.8 全局选项

选项	说明
`--version` / `-V`	显示版本号
`--no-color`	禁用彩色输出
`--help` / `-h`	显示帮助

11.9 环境变量

变量	说明
`OPENSPEC_TELEMETRY`	设为 `0` 禁用遥测
`DO_NOT_TRACK`	设为 `1` 禁用遥测
`OPENSPEC_CONCURRENCY`	并发验证数（默认 6）
`NO_COLOR`	禁用彩色输出

12. 配置系统详解

12.1 配置层级

OpenSpec 的配置有三个层级（优先级从高到低）：

项目级：openspec/config.yaml
用户级：~/.config/openspec/config.yaml
默认值：内置默认配置

12.2 工作流档案

OpenSpec 提供两种工作流档案：

档案	启用的命令	适合场景
Core（默认）	`propose`, `explore`, `apply`, `archive`	快速开发、简单项目
Expanded	全部 11 个命令	复杂项目、精细控制

切换档案：

openspec config profile
# 选择 "Expanded Profile" 解锁全部命令

12.3 投递模式

OpenSpec 支持不同的投递模式来配置 AI 工具集成：

Skills 模式：生成 AI 技能文件（如 .claude/skills/）
Commands 模式：生成斜杠命令文件（如 .cursor/commands/）
Both 模式：同时生成技能和命令文件

13. Schema 自定义工作流

13.1 什么是 Schema？

Schema 定义了工作流的产物类型和依赖关系。默认 Schema 是 spec-driven，包含四个产物：

proposal → specs → design → tasks

13.2 创建自定义 Schema

# 交互式创建
openspec schema init research-first

# 非交互式创建（指定产物）
openspec schema init rapid \
  --description "快速迭代工作流" \
  --artifacts "proposal,tasks" \
  --default

创建后会生成：

openspec/schemas/rapid/
├── schema.yaml           # Schema 定义
└── templates/
    ├── proposal.md
    └── tasks.md

13.3 基于现有 Schema 定制

# 复制 spec-driven Schema 并修改
openspec schema fork spec-driven my-workflow

13.4 Schema 优先级

当同名 Schema 存在于多个位置时，按以下优先级解析：

项目级：openspec/schemas/<name>/
用户级：~/.local/share/openspec/schemas/<name>/
内置：随包内置的 Schema

14. 支持的 AI 工具与命令格式

14.1 完整支持列表

AI 工具	工具 ID	命令格式
Claude Code	`claude`	`/opsx:propose`
Cursor	`cursor`	`/opsx-propose`
Windsurf	`windsurf`	`/opsx-propose`
GitHub Copilot	`github-copilot`	`/opsx-propose`
Gemini CLI	`gemini`	`/opsx:propose`
Codex CLI	`codex`	`/opsx:propose`
CodeBuddy	`codebuddy`	`/opsx:propose`
Qwen Code	`qwen`	`/opsx:propose`
Cline	`cline`	`/opsx:propose`
Trae	`trae`	`/openspec-propose`
Kilo Code	`kilocode`	`/opsx:propose`
Roo Code	`roocode`	`/opsx:propose`
Auggie	`auggie`	`/opsx:propose`
Lingma	`lingma`	`/opsx:propose`
Kimi	`kimi`	`/opsx:propose`

14.2 命令格式差异

关键差异：不同 AI 工具使用不同的分隔符：

格式	使用工具	示例
冒号分隔	Claude Code、Gemini、Codex 等	`/opsx:propose`
连字符分隔	Cursor、Windsurf、Copilot IDE	`/opsx-propose`
全名 + 连字符	Trae	`/openspec-propose`

注意：GitHub Copilot 的 OpenSpec 命令仅在 IDE 扩展中可用（VS Code、JetBrains），CLI 版本不支持自定义提示文件。

15. 完整实战案例：为应用添加暗黑模式

第一步：探索需求

You: /opsx:explore
AI: 你想探索什么？
You: 我们的应用需要支持暗黑模式，但不确定用什么方案
AI: 让我分析一下现有的代码库...
     [呈现 3 种方案对比]
     方案 A: CSS 变量 + Context — 推荐，轻量且兼容
     方案 B: CSS-in-JS 主题 — 功能强但增加依赖
     方案 C: 独立 CSS 文件 — 简单但难以维护
You: 用方案 A

第二步：创建提案

You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
    ✓ proposal.md — 暗黑模式背景、目标、验收标准
    ✓ specs/ui/spec.md — 详细需求和验收场景
    ✓ design.md — CSS 变量方案技术设计
    ✓ tasks.md — 4 阶段 8 项任务
    Ready for implementation. Run /opsx:apply.

第三步：审查产物（推荐）

打开生成的文件，检查是否符合预期：

proposal.md — 目标和验收标准是否合理？
specs/ui/spec.md — 需求是否完整？
design.md — 技术方案是否可行？
tasks.md — 任务拆分是否合理？

如果有不满意的地方，直接修改文件即可。

第四步：执行实现

You: /opsx:apply
AI: Implementing add-dark-mode...
    ✓ 1.1 创建 ThemeContext Provider
    ✓ 1.2 定义 CSS 变量
    ✓ 2.1 创建 ThemeToggle 组件
    ✓ 2.2 集成 localStorage
    ✓ 3.1 适配所有组件
    ✓ 3.2 添加系统偏好检测
    ✓ 4.1 主题切换测试
    ✓ 4.2 持久化测试
    All tasks complete!

第五步：验证

You: /opsx:verify
AI: Verifying add-dark-mode...

    [CRITICAL] None
    [WARNING] 首次加载时未检测 prefers-color-scheme
    [SUGGESTION] 添加主题切换过渡动画

    2 items need attention. Fix and re-verify.

根据验证报告修复问题，然后重新验证直到全部通过。

第六步：归档

You: /opsx:archive
AI: Checking change: add-dark-mode
    ✓ All tasks completed
    ✓ All verification passed
    Sync delta specs? → Yes
    ✓ Synced specs to openspec/specs/ui/spec.md
    ✓ Moved to openspec/changes/archive/2026-05-15-add-dark-mode/
    Change archived successfully.

16. 多场景工作流模式

场景一：复杂功能开发（逐步推进）

/opsx:explore    → 讨论需求，研究技术方案
/opsx:new        → 创建变更框架
/opsx:continue   → 生成 proposal → 审查
/opsx:continue   → 生成 specs → 审查
/opsx:continue   → 生成 design → 审查
/opsx:continue   → 生成 tasks → 最终确认
/opsx:apply      → 逐项执行任务
/opsx:verify     → 验证代码与规范一致性
/opsx:sync       → 同步 Delta 规范
/opsx:archive    → 归档变更

场景二：快速小迭代

/opsx:ff         → 一次性生成所有规划产物
/opsx:apply      → 执行任务
/opsx:verify     → 快速验证
/opsx:archive    → 归档

场景三：核心三步流（最简方式）

/opsx:propose    → 提案 + 一步生成所有产物
/opsx:apply      → 执行
/opsx:archive    → 归档

场景四：团队协作

# 项目开始时：建立全局规范
/opsx:explore    → 团队讨论规范
/opsx:new        → 创建规范变更
/opsx:continue   → 逐步建立规范

# 每个功能开发
/opsx:propose    → 基于全局规范创建变更
/opsx:apply      → 实现
/opsx:sync       → 同步新规范到主库
/opsx:archive    → 归档

# 多人完成多个变更后
/opsx:bulk-archive → 批量归档，自动检测冲突

17. 最佳实践

规范编写

先探索，再提案：对于复杂需求，先用 /opsx:explore 充分讨论
验收标准要具体：避免"用户体验好"这类模糊描述，用"页面加载 < 2s"等可量化的标准
Delta 规范聚焦变化：只记录与主规范的差异，不要重写整个文档

工作流选择

简单变更用核心三步流：propose → apply → archive
复杂变更用逐步推进：new → continue → ... → apply → verify → archive
紧急修复可以跳过部分步骤：OpenSpec 不会阻止你跳过，但建议至少有 proposal 和 tasks

产物管理

生成后一定要审查：AI 生成的产物不一定完全符合你的意图
可以随时修改任何产物：修改 tasks.md 后，apply 会按新的任务列表执行
归档前运行 verify：发现代码与规范的"漂移"，减少技术债务

团队协作

统一 Schema：团队使用相同的 Schema，确保产出格式一致
及时 sync：长周期变更及时同步规范，避免并行变更的规范冲突
使用 bulk-archive：多个变更完成后批量归档，自动检测冲突

CI/CD 集成

用 JSON 输出做自动化：openspec validate --all --json 适合在 CI 中运行
严格模式验证：openspec validate --strict 在发布前运行

18. 常见问题与解决方案

Q1: AI 工具中看不到斜杠命令

解决方案：

运行 openspec update 刷新指令文件
重启 AI 编辑器（Cursor、VS Code 等）
确认项目根目录存在 openspec/ 目录
确认使用了支持斜杠命令的 AI 工具

Q2: `/opsx:ff` 和 `/opsx:continue` 怎么选？

命令	适合场景
`/opsx:ff`	需求清晰、变更简单、一步到位
`/opsx:continue`	需求复杂、需要逐步审查、降低风险

Q3: `/opsx:sync` 和 `/opsx:archive` 的区别？

命令	是否同步规范	是否归档	变更状态
`/opsx:sync`	是	否	保持活跃
`/opsx:archive`	是（自动）	是	移入归档

Q4: 如何查看当前变更的进度？

# CLI 方式
openspec status

# 或查看变更目录中的文件
ls openspec/changes/<change-name>/
# 如果 tasks.md 存在，规划阶段已完成

Q5: 如何在已有项目中引入 OpenSpec？

# 在项目根目录初始化
openspec init --tools <你的AI工具>

# 用 onboard 快速上手
/opsx:onboard

Q6: 切换到 Expanded Profile 后命令还是只有 4 个？

# 1. 切换档案
openspec config profile
# 选择 "Expanded Profile"

# 2. 刷新项目指令
openspec update

# 3. 重启 AI 编辑器
# 关闭并重新打开 Cursor / VS Code

Q7: 如何禁用遥测？

# 方式一：环境变量
export OPENSPEC_TELEMETRY=0

# 方式二：标准 DNT 信号
export DO_NOT_TRACK=1

# 方式三：配置
openspec config set telemetry.enabled false

Q8: 如何在 CI 中使用 OpenSpec 验证？

# 安装
npm install @fission-ai/openspec

# 运行验证
openspec validate --all --strict --json

# 退出码：0=成功，1=验证失败

19. 总结

OpenSpec 通过轻量级规范层，让 AI 编码助手真正理解你的意图：

核心步骤	做什么	命令
Propose	创建变更 + 所有规划产物	`/opsx:propose`
Apply	执行任务，生成代码	`/opsx:apply`
Archive	归档变更，同步规范	`/opsx:archive`

三个核心原则：

先对齐再编码——人类和 AI 先就规范达成一致
流动而非僵化——随时更新任何产物，没有死板的阶段关卡
迭代而非瀑布——逐步精炼，而非一次成型

从哪里开始？

# 1. 安装
npm install -g @fission-ai/openspec@latest

# 2. 在项目中初始化
cd your-project
openspec init --tools <你的AI工具>

# 3. 运行入门引导（强烈推荐！）
/opsx:onboard

参考资源

项目仓库: github.com/Fission-AI/OpenSpec

中文文档: lzw.me/docs/OpenSpec-Docs-zh

CLI 参考: lzw.me/docs/openspec/zh-CN/cli.html

Discord 社区: discord.gg/YctCnvvshC

企业版咨询: teams@openspec.dev

posted @ 2026-05-15 13:47 helloHKTK 阅读(2108) 评论(0) 收藏举报

刷新页面返回顶部