OpenSpec 完整使用流程笔记（SDD)

📌 什么是 OpenSpec？

OpenSpec 是一个 AI 辅助开发的结构化工作流工具。它通过一系列斜杠命令（/opsx:）引导开发者与 AI 协作，从需求探索、规划、编码到验证、归档，每一步都清晰可控，避免沟通偏差，提升开发效率和质量。

OpenSpec 的核心思想是 "先约定，后编码" ------在写代码前，先与 AI 共同明确需求、设计规范、拆解任务；代码实现后，再验证其是否符合约定，最后归档变更，形成可追溯的历史记录。

🚀 快速开始：安装与初始化

1. 安装 OpenSpec CLI

bash

csharp 复制代码

npm install -g openspec
# 或使用 yarn
yarn global add openspec

2. 在项目中初始化

进入你的项目根目录，执行：

bash

csharp 复制代码

openspec init

这将创建必要的目录结构（如 openspec/、changes/ 等）和配置文件。

⚙️ 配置工作流：启用全部命令

OpenSpec 默认只启用核心命令（explore、apply、archive 等 4 个）。要使用完整功能（包括 new、continue、ff、verify、sync 等 11 个命令），需要切换配置文件。

步骤

切换 Profile

bash
arduino 复制代码
```
openspec config profile
```
选择 Expanded Profile（完整工作流）。
手动选择 Workflows（可选）

如果你只想启用部分命令，可以选择 Workflows only，然后用空格键勾选/取消具体命令。
刷新配置

bash
sql 复制代码
```
openspec update
```
重启 AI 编辑器（如 Cursor、VS Code + Copilot），使新的斜杠命令生效。

现在，你的 AI 编辑器中将出现所有 /opsx: 命令。

📚 核心概念

变更（Change） ：一次独立的开发任务，对应一个需求或功能点。每个变更在 changes/ 下拥有一个独立目录（如 changes/20250311-add-login/）。
工件（Artifact） ：变更过程中的产出物，包括提案（proposal）、规范（specs）、设计（design）、任务清单（tasks）、代码实现、验证报告等。
规范（Specs） ：记录项目全局或模块的设计约定，存储在 openspec/specs/ 中，可被多个变更共享。
快进（Fast-forward） ：一次性生成规划阶段的所有工件，跳过逐步创建的中间步骤。

🧭 分阶段流程详解

一个完整的 OpenSpec 工作流分为 探索 → 规划 → 执行 → 验证 → 同步 → 归档 六个阶段。

1. 探索阶段：`/opsx:explore`

在动手写代码前，与 AI 进行纯粹的讨论，分析需求、调研技术方案、梳理潜在风险。

命令：/opsx:explore
适用场景：需求模糊、技术选型不确定、需要头脑风暴。
行为：AI 进入"只读模式"，不会创建任何文件，只生成讨论性回答。
输出：通常是一段对话记录，可手动保存到项目文档中作为参考。

2. 规划阶段：从想法到任务清单

规划阶段的目标是产出清晰的 提案、规范、设计和任务清单，作为后续编码的依据。

2.1 启动新变更：`/opsx:new`

命令：/opsx:new
行为：在 changes/ 下创建一个以当前时间戳命名的新目录，并生成基础文件框架（如 proposal.md、tasks.md 等占位文件）。
提示：需要你描述本次变更的目标（一句话或一段文字）。

2.2 逐步完善：`/opsx:continue`

如果你希望按顺序创建每个工件，可以使用 continue 命令逐个推进。

命令：/opsx:continue
行为：根据当前变更的进度，生成下一个缺失的工件。例如，已有 proposal.md，运行 continue 会生成 specs/ 目录和初步规范；再运行一次生成 design.md；再运行生成 tasks.md。
优点：每一步你都可以审查、修改，确保方向正确。

2.3 快速完成规划：`/opsx:ff`（快进）

如果你对需求很明确，希望 AI 一次性生成所有规划工件，直接进入编码阶段，可以使用快进命令。

命令：/opsx:ff
行为：一次性生成 proposal.md、specs/（含规范）、design.md、tasks.md。
适用场景：需求清晰、变更范围小、经验丰富的开发者。

规划阶段产出物

proposal.md：描述变更的背景、目标、验收标准。
specs/ ：存放与该变更相关的详细规范（接口设计、数据结构、UI 约定等）。
design.md：技术设计方案，包括模块划分、关键算法、依赖等。
tasks.md ：拆解后的可执行任务清单（通常带复选框），供后续 apply 使用。

3. 执行阶段：`/opsx:apply`

当任务清单准备就绪后，就可以让 AI 根据任务列表编写代码。

命令：/opsx:apply
行为：AI 读取当前变更下的 tasks.md，逐个任务生成代码，并将代码文件放到项目中的正确位置。
交互：每完成一个任务，AI 可能会请求确认或提供解释；你也可以中途打断，修改任务清单后继续。

4. 验证阶段：`/opsx:verify`

代码实现后，需要检查其是否完全符合当初制定的规范和设计。

命令：/opsx:verify
行为：AI 分析变更中的代码，对照 specs/ 和 design.md 进行一致性检查，生成一份 验证报告 （通常在变更目录下生成 verify-report.md）。
报告内容：指出符合项、不符合项、潜在问题、建议修复方案。
后续：如果发现问题，可以手动修改代码或调整规范，然后再次运行 verify 直至通过。

5. 同步规范：`/opsx:sync`

在变更过程中，你可能会产生新的、可复用的规范（如一个通用的组件接口、API 设计模式）。这些规范应该合并到项目的主规范库中，供未来变更使用。

命令：/opsx:sync
行为：将当前变更中新增或修改的规范文件（位于 changes/<change>/specs/）复制或合并到项目根目录的 openspec/specs/ 中。
注意：此命令不会归档变更，变更本身仍处于活跃状态，可继续开发。

6. 归档阶段：`/opsx:archive` 与 `/opsx:bulk-archive`

当变更所有工作（编码、验证）完成，并已同步规范后，就可以归档本次变更。

6.1 单个归档：`/opsx:archive`

命令：/opsx:archive
行为：
- 将变更目录从 changes/active/ 移动到 changes/archived/（按日期组织）。
- 再次运行 sync（确保最新规范已合并）。
- 更新变更日志（CHANGELOG.md）。
- 标记变更状态为"已完成"。

6.2 批量归档：`/opsx:bulk-archive`

当有多个已完成变更等待归档时，使用此命令批量处理。

命令：/opsx:bulk-archive
行为：
- 列出所有可归档的活跃变更。
- 让你选择要归档的变更（可多选）。
- 依次执行归档操作，并自动检测规范冲突（如果两个变更修改了同一规范文件，会提示手动解决）。
- 更新变更日志。

📋 命令速查表

命令	阶段	功能
`/opsx:explore`	探索	只读模式讨论需求，不生成文件
`/opsx:new`	规划	创建新变更目录及基础文件
`/opsx:continue`	规划	按进度生成下一个工件
`/opsx:ff`	规划	快进：一次性生成所有规划工件
`/opsx:apply`	执行	根据任务清单编写代码
`/opsx:verify`	验证	检查代码是否符合规范，生成报告
`/opsx:sync`	同步	将变更中的规范合并到主规范库
`/opsx:archive`	归档	归档单个已完成变更
`/opsx:bulk-archive`	归档	批量归档多个变更
`/opsx:onboard`	学习	交互式教程（约15分钟）

💡 最佳实践与典型场景

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

/opsx:explore -- 与 AI 讨论需求、技术选型。
/opsx:new -- 创建变更。
/opsx:continue -- 生成 proposal，审阅后继续。
/opsx:continue -- 生成 specs，审阅后继续。
/opsx:continue -- 生成 design，审阅后继续。
/opsx:continue -- 生成 tasks，审阅后定稿。
/opsx:apply -- 执行任务清单，生成代码。
/opsx:verify -- 验证代码一致性，修复问题。
/opsx:sync -- 将新增规范合并到主库。
/opsx:archive -- 归档变更。

场景二：小型快速迭代

/opsx:ff -- 快进生成所有规划工件（需确保需求明确）。
/opsx:apply -- 编码。
/opsx:verify -- 验证。
/opsx:archive -- 归档。

场景三：规范先行，团队协作

在项目启动时，先通过 /opsx:explore 和 /opsx:new 建立全局规范（如代码风格、API 设计原则），并存放在 openspec/specs/ 中。
后续每个功能变更，都从主规范派生，开发完成后通过 /opsx:sync 更新主规范，确保团队知识库同步。

❓ 常见问题

Q1：命令在我的编辑器中不显示怎么办？

确保已运行 openspec update。
重启编辑器（Cursor / VS Code）。
检查项目根目录下是否存在 .openspec/ 和 openspec/ 文件夹。
确认你正在使用支持斜杠命令的 AI 工具（如 Cursor、Claude Code）。

Q2：`/opsx:ff` 和 `/opsx:continue` 有什么区别？

ff 是一次性生成所有规划工件，适合需求明确、变更简单时使用；continue 是逐个生成，适合需要逐步审阅、风险较高的变更。

Q3：如何查看当前变更的进度？

AI 会记录当前变更的状态，你也可以直接查看变更目录下的文件。例如，如果 tasks.md 已存在，说明规划阶段已完成。

Q4：`sync` 和 `archive` 都需要更新规范，有什么区别？

sync 只合并规范，变更本身仍活跃，可继续开发。
archive 在归档前会自动执行一次 sync，确保规范已被合并，然后归档变更。

🎯 总结

OpenSpec 通过结构化的命令和工作流，将 AI 从"代码生成器"转变为"遵循规范的协作者"。掌握这些命令，你就能：

在探索阶段利用 AI 进行深度分析。
在规划阶段与 AI 共同构建清晰的设计蓝图。
在执行阶段让 AI 按任务清单精准编码。
在验证阶段自动检查一致性，避免返工。
在归档阶段沉淀规范，积累团队资产。

开始使用 OpenSpec，让 AI 辅助开发变得更加可控、高效！

OpenSpec 完整使用流程笔记 （SDD)