核心摘要

这篇 OpenSpec 教程 将手把手教你如何在日常开发中落地 SDD 开发 (Spec-Driven Development)。只需掌握三条核心斜杠命令（/opsx:propose、/opsx:apply、/opsx:archive），你就能把不可控的 AI 对话变成结构化、高可靠的工程管线，大幅降低代码幻觉并提升可维护性。

📋 目录

✨ 核心要点

  • 结构化工作流：OpenSpec 将 AI 编程从"散漫聊天"升级为"规格驱动"的严密管线。
  • 三命令法则：整个变更生命周期完全由 /opsx:propose、/opsx:apply 和 /opsx:archive 掌控。
  • 终结 AI 幻觉：通过任务拆解和精确的上下文限制，AI 幻觉发生率断崖式下降。
  • 全生态兼容：在 Cursor、Windsurf、Trae、Claude Code 中无缝运行。

💡 快速工具: 使用我们免费的在线 Markdown 编辑器，在将 spec.md 喂给 AI 之前，先在线起草并预览你的规格文档。

什么是 SDD (Spec-Driven Development) 开发？

SDD (Spec-Driven Development，规格驱动开发) 是一种 AI 原生的编程范式。在这个范式下，规格说明书（Spec）是首要产物，而代码完全从中派生。开发者不再跟 AI 漫无目的地闲聊，而是通过结构化的文档定义系统的行为和边界，AI Agent 则在这些严格的约束下执行具体的代码编写。

在传统的敏捷开发中，需求文档往往在写下第一行代码时就过时了。但在 SDD 中，规格文档是单一事实来源 (Single Source of Truth, SSOT)。如果需求变更，你必须先改文档，而不是先改代码。

📝 术语链接: 提示工程 (Prompt Engineering) — 了解更多关于提示工程的定义。从本质上讲，SDD 开发就是面向 AI 编程助手的最高级别、系统级的提示工程。

OpenSpec 是如何工作的

OpenSpec 是目前最受瞩目的开源 SDD 框架，由 Fission-AI 团队研发。它提供了一套极轻量级的目录结构，让 AI Agent 能轻松解析并严格执行。

OpenSpec 的核心哲学是 "fluid not rigid"（灵活而不僵化）。它不强制要求你画复杂的 UML 类图，而是推荐使用诸如 WHEN/THEN 这样简单的 BDD（行为驱动开发）语法来描述业务场景。

graph LR A["1. /opsx:propose"] -->|生成规格| B["specs/ & tasks.md"] B -->|人工审查| C["2. /opsx:apply"] C -->|执行代码| D["代码变更"] D -->|测试通过| E["3. /opsx:archive"] style A fill:#e1f5fe,stroke:#01579b style C fill:#fff3e0,stroke:#e65100 style E fill:#e8f5e9,stroke:#2e7d32

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 并初始化你的项目。

bash 
# 全局安装 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 命令：

你的输入：

text 
/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 看起来应该像这样：

markdown 
### 需求：JSON 验证逻辑

#### 场景：有效的 JSON 输入
- **WHEN** 用户输入 `{"key": "value"}` 并点击验证
- **THEN** 系统显示一条绿色的成功提示
- **AND** 将 JSON 格式化为 2 个空格缩进

#### 场景：无效的 JSON 输入
- **WHEN** 用户输入 `{"key": "value"`（少了一个大括号）
- **THEN** 系统捕获 SyntaxError
- **AND** 精确指出错误发生在哪一行

步骤 3: 执行任务 (Apply)

当你对生成的规格和任务清单感到满意后，就可以让 AI 开始写代码了。

你的输入：

text 
/opsx:apply add-json-validator-feature

此时，AI 会逐条读取 tasks.md，并在完成每一项代码修改后打上勾。这种"强迫" AI 按清单执行的方式，能有效防止它在庞大的代码库中迷失方向——这正是 Vibe Coding 常犯的错。

步骤 4: 归档变更 (Archive)

代码写完且测试通过后，你必须将这次变更归档。这对项目的长期记忆至关重要。

你的输入：

text 
/opsx:archive add-json-validator-feature

AI 会将这个变更文件夹移动到 openspec/changes/archive/[日期]-add-json-validator-feature/ 中。未来，当新的 AI 模型接入时，它可以通过阅读这些归档文件，瞬间明白之前架构决策的"来龙去脉"。

🔧 立即体验：在开发数据密集型应用时，你可以使用我们免费的 在线 JSON 格式化工具 来实时验证你的测试数据。

OpenSpec 高级使用技巧

1. 将 OpenSpec 与 CLAUDE.md 结合

OpenSpec 负责管理具体功能的生命周期，而 CLAUDE.md 则负责项目的全局法则。

为了获得最佳的 SDD 开发体验，建议在 CLAUDE.md 中定义全局约束：

markdown 
# 项目总纲
- 我们只使用 React 函数式组件。
- 绝不使用内联 CSS，统一使用 CSS Modules。
- 所有新功能必须通过 OpenSpec `/opsx:propose` 流程开发。

2. 处理任务执行中的偏差

如果 AI 在执行 /opsx:apply 时遇到意外（比如某个依赖库被弃用了），不要直接在对话框里让它"随便找个替代方案"。 正确的做法是：停止 apply 流程，手动修改 specs/spec.md 和 tasks.md 以反映新的技术现实，然后再恢复 /opsx:apply。只有这样，你的单一事实来源（SSOT）才不会失效。

SDD 开发最佳实践

  1. 规格要灵活，不要死板 — 重点描述 是什么 和 为什么（如边界条件、异常处理），不要把具体代码写进规格里。
  2. 原子化提案 — 不要一次性 propose "开发整个电商后台"。先 propose "add-user-auth"，再 propose "add-product-catalog"。
  3. 永远不要跳过归档 — 必须执行 /opsx:archive。未归档的变更会一直堆积在工作区，严重干扰 AI 的上下文判断。
  4. 使用高推理能力模型 — 在 Propose 阶段，务必使用 Claude 3.5 Sonnet 或 GPT-4o 级别的高级模型。

⚠️ 常见错误:

  • 边做边改需求 → 如果想法变了，先去改 spec.md。不要试图通过聊天让 AI 偏离原定计划。
  • 跳过审查阶段 → 在运行 /opsx:apply 之前，人类必须先看一遍生成的 tasks.md。

常见问题 (FAQ)

Q1: 我能在老项目（Brownfield）中使用 OpenSpec 吗？

完全可以，OpenSpec 支持渐进式引入。在老仓库根目录运行 openspec init，下次修 Bug 或做小功能时，直接使用 /opsx:propose 即可。你不需要为历史遗留代码补写 Spec，只用它管理未来的增量变更。

Q2: SDD 开发会拖慢我的编码速度吗？

在前 10 分钟确实会，因为你得花时间审阅规格文档，而不是马上看到代码哗哗生成。但把时间拉长到一个 2 周的 Sprint 来看，SDD 极大地减少了调试时间、代码回退和"AI 幻觉死循环"，综合效能远超纯对话式编程。

Q3: OpenSpec 和 Cursor Rules 有什么区别？

Cursor Rules（.cursorrules）决定了 AI 如何写代码（语法、风格）；而 OpenSpec 决定了 AI 写什么并管理整个工作流。两者是绝佳的互补关系。

Q4: 必须用 AI IDE 才能跑 OpenSpec 吗？

从技术上讲，你可以手写 spec.md 然后通过 CLI 工具执行它，但这违背了初衷。当你直接在 AI 助手的对话框里输入斜杠命令时，OpenSpec 才能发挥出最大的魔力。

总结

通过这篇 OpenSpec 教程，你应该已经掌握了在 2026 年大规模落地 AI 工程化的核心密码——SDD (Spec-Driven Development)。严格遵守 /opsx:propose → /opsx:apply → /opsx:archive 工作流，你就能把充满不确定性的 AI 变成一座精准、可靠的软件兵工厂。

立刻在你的下一个项目中尝试 SDD，彻底告别 AI 幻觉！

👉 立即使用 Markdown Editor — 离线起草 OpenSpec 提案的完美助手。

相关资源