核心摘要
这篇 OpenSpec 教程 只讲操作流程：初始化仓库，用 /opsx:propose 创建可审查的变更文档，完成人工审查，用 /opsx:apply 执行任务，验证行为，再用 /opsx:archive 保留完成记录。结构化流程能提高可追踪性；正确性仍来自审查和可执行证据。
📋 目录
✨ 核心要点
- 结构化工作流：OpenSpec 将 AI 编程从"散漫聊天"升级为"规格驱动"的管线，并留下可审查的记录。
- 三命令法则：日常变更生命周期由
/opsx:propose、/opsx:apply和/opsx:archive掌控。 - 控制修改范围：任务拆解和上下文限制可能减少无关改动，但效果必须根据代码差异和测试结果判断。
- 不绑定工具：在 Cursor、Windsurf、Trae、Claude Code 等助手中都能运行，不绑定单一 IDE 或模型。
操作前提：一个经过审查的变更
OpenSpec 假定一次变更已经明确意图、场景、约束与任务，并且这些文档会与实现保持同步。执行下方命令前，请先通过 Spec Coding 完全指南了解方法论与框架边界。本文所说的“单一事实来源”，是团队选定并审查、用于管理本次变更的一组文档；文件本身不会自动执行约束。
OpenSpec 是如何工作的
OpenSpec 是一个流行的开源 SDD 框架，由 Fission-AI 团队研发。它提供了一套极轻量级的目录结构，让 AI Agent 能轻松解析并严格执行。
OpenSpec 的核心哲学是 "fluid not rigid"（灵活而不僵化）。它不强制要求你画复杂的 UML 类图，而是推荐使用诸如 WHEN/THEN 这样简单的 BDD（行为驱动开发）语法来描述业务场景。
OpenSpec 的三大支柱命令
| 命令 | SDD 阶段 | 作用 |
|---|---|---|
/opsx:propose |
定义 (Definition) | 生成 proposal.md、specs/ 和 tasks.md 等核心文档。 |
/opsx:apply |
执行 (Execution) | 指示 AI 读取 tasks.md，按部就班地实现代码逻辑。 |
/opsx:archive |
持久化 (Persistence) | 将已完成的规格归档，形成项目的历史记忆。 |
OpenSpec 教程：实战步骤详解
让我们进入这篇 OpenSpec 教程 的实战部分。我们将用 SDD 的方式为一个项目添加一个简单的 "JSON 验证器" 功能。
步骤 1: 安装与初始化
首先，全局安装 OpenSpec 并初始化你的项目。
# 全局安装 OpenSpec
npm install -g @fission-ai/openspec@latest
# 进入你的项目根目录并初始化
cd my-ai-project
openspec init
这会在你的项目根目录生成一个 openspec/ 文件夹。至此，AI 理解 SDD 工作流所需的基础脚手架就搭建完毕了。
步骤 2: 提出变更 (Propose)
在你的 AI IDE（如 Cursor 或 Trae）的对话框中，不要直接说"帮我写个 JSON 验证器"，而是使用 propose 命令：
你的输入：
/opsx:propose add-json-validator-feature
AI 会在 openspec/changes/add-json-validator-feature/ 目录下生成几个文件：
proposal.md: 宏观目标与背景。specs/spec.md: 使用 WHEN/THEN 语法的详细需求。tasks.md: 原子化的实施清单。
审查 specs/spec.md：
仔细检查 AI 是否准确捕获了你的意图。一份合格的 Spec 看起来应该像这样：
### 需求：JSON 验证逻辑
#### 场景：有效的 JSON 输入
- **WHEN** 用户输入 `{"key": "value"}` 并点击验证
- **THEN** 系统显示一条绿色的成功提示
- **AND** 将 JSON 格式化为 2 个空格缩进
#### 场景：无效的 JSON 输入
- **WHEN** 用户输入 `{"key": "value"`（少了一个大括号）
- **THEN** 系统捕获 SyntaxError
- **AND** 精确指出错误发生在哪一行
步骤 3: 执行任务 (Apply)
当你对生成的规格和任务清单感到满意后，就可以让 AI 开始写代码了。
你的输入：
/opsx:apply add-json-validator-feature
此时，AI 会逐条读取 tasks.md，并在完成每一项代码修改后打上勾。这种"强迫" AI 按清单执行的方式，能有效防止它在庞大的代码库中迷失方向——这正是 Vibe Coding 常犯的错。
步骤 4: 归档变更 (Archive)
代码写完且测试通过后，你必须将这次变更归档。这对项目的长期记忆至关重要。
你的输入：
/opsx:archive add-json-validator-feature
AI 会将这个变更文件夹移动到 openspec/changes/archive/[日期]-add-json-validator-feature/ 中。未来，当新的 AI 模型接入时，它可以通过阅读这些归档文件，瞬间明白之前架构决策的"来龙去脉"。
OpenSpec 高级使用技巧
1. 将 OpenSpec 与 CLAUDE.md 结合
OpenSpec 负责管理具体功能的生命周期，而 CLAUDE.md 则负责项目的全局法则。
为了获得更顺畅的 SDD 开发体验，建议在 CLAUDE.md 中记录全局约定：
# 项目总纲
- 我们只使用 React 函数式组件。
- 绝不使用内联 CSS，统一使用 CSS Modules。
- 所有新功能建议通过 OpenSpec `/opsx:propose` 流程开发。
请把 CLAUDE.md 当作约定辅助（convention aid），而不是强制机制：它能塑造模型的产出、减少明显跑偏，但模型仍可能忽略其中某一条。它不是构建关卡，更不是安全边界——真正的护栏（测试、Lint、CI、访问控制）要放在提示词之外。
2. 处理任务执行中的偏差
如果 AI 在执行 /opsx:apply 时遇到意外（比如某个依赖库被弃用了），不要直接在对话框里让它"随便找个替代方案"。
正确的做法是：停止 apply 流程，手动修改 specs/spec.md 和 tasks.md 以反映新的技术现实，然后再恢复 /opsx:apply。只有这样，你的单一事实来源（SSOT）才不会失效。
SDD 开发最佳实践
- 规格要灵活，不要死板 — 重点描述 是什么 和 为什么（如边界条件、异常处理），不要把具体代码写进规格里。
- 原子化提案 — 不要一次性 propose "开发整个电商后台"。先 propose "add-user-auth"，再 propose "add-product-catalog"。
- 妥善关闭已完成变更 — 验证后按仓库工作流归档变更文档；不要为了清空工作区而归档未经验证或只执行了一部分的变更。
- 按任务选择模型 — Propose 阶段通常需要较强的分析和规划能力，但模型名称变化很快。应使用真实变更比较场景完整性、约束遵循、延迟和成本，而不是直接锁定某个厂商标为“顶级”的版本。
⚠️ 常见错误:
- 边做边改需求 → 如果想法变了，先去改
spec.md。不要试图通过聊天让 AI 偏离原定计划。 - 跳过审查阶段 → 在运行
/opsx:apply之前，人类必须先看一遍生成的tasks.md。
常见问题 (FAQ)
Q1: 我能在老项目（Brownfield）中使用 OpenSpec 吗？
可以渐进式引入。先在分支中按当前 README 运行 openspec init，从一个范围小、验收清晰的修复或功能开始，并检查生成文件是否与现有仓库规范冲突。是否补写历史规格应按风险和维护需求决定，不必为了采用工具一次性覆盖全部遗留代码。
Q2: SDD 开发会拖慢我的编码速度吗？
它会增加前期编写与审查成本。能否减少后续调试和返工，取决于变更复杂度、团队执行情况、文档质量和检查流程。应与可比基线对照，衡量交付周期、审查时间、上线后缺陷和返工量，而不是假定它一定能提升效率。
Q3: OpenSpec 和 Cursor Rules 有什么区别？
Cursor Rules（.cursorrules）主要约束 AI 如何写代码，例如语法和风格；OpenSpec 则描述 AI 要实现什么，并管理变更流程。两者职责不同，可以配合使用。
Q4: 必须用 AI IDE 才能跑 OpenSpec 吗？
可以，但要以当前 OpenSpec 文档列出的 CLI 和客户端集成为准。关键是所选界面创建、读取并更新同一组经过审查的变更文档；IDE 对话界面只是操作更方便，并不能保证结果正确。
总结
OpenSpec 的 /opsx:propose → 审查 → /opsx:apply → 验证 → /opsx:archive 流程，为 AI 辅助变更建立可审查记录。它的价值在于可追踪性和明确的检查点，而不是保证代码质量。归档前应保持文档与实现同步、检查代码差异、运行项目要求的检查并记录偏差。
相关资源
- Spec Coding 完全指南 — 深入理解 SDD 理论
- Spec Coding 实战指南 — Fission-AI 官方实践解析
- JSON 术语解析
- 提示工程术语解析