📌 什么是 OpenSpec？
OpenSpec 是一个 AI 辅助开发的结构化工作流工具。它通过一系列斜杠命令（/opsx:）引导开发者与 AI 协作，从需求探索、规划、编码到验证、归档，每一步都清晰可控，避免沟通偏差，提升开发效率和质量。
OpenSpec 的核心思想是 “先约定，后编码” ——在写代码前，先与 AI 共同明确需求、设计规范、拆解任务；代码实现后，再验证其是否符合约定，最后归档变更，形成可追溯的历史记录。
🚀 快速开始：安装与初始化
1. 安装 OpenSpec CLI
bash
npm install -g @fission-ai/openspec@latest
2. 在项目中初始化
进入你的项目根目录，执行：
bash
openspec init
这将创建必要的目录结构（如 openspec/、changes/ 等）和配置文件。
⚙️ 配置工作流：启用全部命令
OpenSpec 默认只启用核心命令（explore、apply、archive 等 4 个）。要使用完整功能（包括 new、continue、ff、verify、sync 等 11 个命令），需要切换配置文件。
步骤
-
切换 Profile
bash
openspec config profile选择
Expanded Profile（完整工作流）。 -
手动选择 Workflows（可选）
如果你只想启用部分命令，可以选择Workflows only，然后用空格键勾选/取消具体命令。 -
刷新配置
bash
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 辅助开发变得更加可控、高效！
