规格驱动开发（SDD）、Spec‑Kit 与 OpenSpec 在 Cursor 中的应用实践

一、什么是 SDD？

1. 背景：为什么需要规格驱动开发？

在使用 Copilot、Cursor、Claude Code 等 AI 编码助手时，常见几个问题：

• 需求只在聊天里：聊着聊着就跑题，多轮后 AI 开始“瞎编”；
• 实现不一致：同一功能反复生成，风格和边界条件都不一样；
• 不可追溯：代码改了一堆，后来没人说得清“当时为什么这么改”。

这种主要靠感觉和聊天驱动的方式，经常被称为「氛围编程」（vibe coding）。

2. SDD 的核心思想

规格驱动开发（Spec‑Driven Development，SDD）的目的，就是用结构化规格文档来约束 AI，避免“氛围编程”。核心有四点：

1. 规范先行，而不是代码先行
   写代码前先写规格（spec）文档，至少要明确：
   • 业务场景和用户故事
   • 输入 / 输出及边界条件
   • 约束和非功能性需求（性能、安全、合规等）
2. 规格是唯一真相（Single Source of Truth）
   规格文件是项目的“法律文本”：
   • 所有计划、任务拆分和代码实现都要对齐规格；
   • 需求变更时，先改规格，再让 AI 按新规格调整代码。
3. 规格可执行、可验证
   规格采用结构化 Markdown / YAML 等格式，便于：
   • 驱动 AI 生成技术方案和任务列表；
   • 自动派生测试用例和验收标准。
4. 设置清晰的决策检查点
   通常流程为：

   规格 → 计划 → 任务 → 实现 → 测试 / 回归

   每一步都要求：

   • 人类审阅；
   • 必要时退回上一步，先改规格而不是直接打补丁。

简单说：SDD 就是把“想清楚”变成一个有文档、有流程的必经步骤，然后用工具让 AI 严格按规格办事。

二、Spec‑Kit：GitHub 官方的 SDD 工具包

1. 它解决什么问题？

Spec‑Kit 是 GitHub 推出的开源工具包，用来帮你在各种 AI 编码环境中（如 Copilot、Cursor 等）按 SDD 的方式工作。它把“写规格、做计划、拆任务、实现和审查”这一整套流程固化成可复用的命令和模板。

主要组成包括：

• CLI 工具：初始化项目、生成目录和基础文件；
• Prompt / Slash 命令模板：针对产品、架构、开发、测试等不同“角色”预置好提示词；
• 标准文件结构：如
  • CONSTITUTION.md：项目“宪法”（目标、边界、约束）
  • spec.md：规格
  • plan.md：技术方案
  • tasks.md：任务列表
• 集成适配：预设好在 Cursor 等 IDE 中使用的 Slash 命令。

2. 典型工作流（配合 Slash 命令）

在 Cursor 这类 IDE 中，Spec‑Kit 通常通过一组 Slash 命令工作：

1. /speckit.constitution
   生成 CONSTITUTION.md，明确项目目标、边界、约束和团队约定。

2. /speckit.specify
   生成或更新 spec.md，聚焦业务需求和用户视角。

3. /speckit.plan
   生成 plan.md，设计架构、模块划分、接口和数据流。

4. /speckit.tasks
   生成 tasks.md，将计划拆分为可执行的小任务，每个任务都带验收标准。

5. /speckit.implement
   让 AI 按任务列表逐条实现、修改代码。

部分实践中，还会再加上 /speckit.review、/speckit.qa 之类的命令，做最终质量闸门。

整体可以概括为：

宪法 → 规格 → 计划 → 任务 → 实现 → 审查 / 测试

3. 适用场景与局限

优势：

• 流程完整清晰，尤其适合 0→1 新项目；
• 支持多种 AI 工具（不仅限于 Cursor）；
• 天然支持“先规格、再测试”的工程纪律。

局限：

• 仪式感较强，对个人开发者或很小的改动显得“太重”；
• 针对已有大型代码库的一些细粒度变更，会感觉步骤偏多；
• 命令多、概念多，需要一定学习成本。

三、OpenSpec：更轻量的 SDD 框架

1. OpenSpec 是什么？

OpenSpec 是一个由 Fission‑AI 团队开源的、面向多种 AI 编码助手的 轻量级 SDD 框架，主打：

• 对已有项目更友好；
• 流程极简；
• 不强依赖某个特定 IDE 或模型。

它的目标可以简化为：

“比 Spec‑Kit 更轻，但比 IDE 自带的简单 Plan 更有结构。”

2. 目录结构与核心概念

典型目录结构：

openspec/
  specs/      # 稳定、长期存在的规格（系统怎么应该工作）
  changes/    # 具体变更提案（这次要改什么、为什么改）
  archive/    # 完成并上线的变更提案
  AGENTS.md   # 当前项目所用 AI 工具配置和说明

OpenSpec 把「一次具体的修改」视为一个 Proposal（提案），通过文件来跟踪：

• 提案内容；
• 关联的规格和模块；
• 实现与验收情况。

3. 三步工作流

OpenSpec 刻意 只保留极简三步：

1). Proposal（提案）

命令示例：

openspec proposal "Add JWT refresh token support"

或在 Cursor 中：

/openspec:proposal "Add JWT refresh token support"

结果：在 changes/ 下生成一份变更文档草稿。

2). Review（审查 / 精炼）

• 和同事或 AI 一起编辑这份提案文档，补充背景、需求、边界、升级影响等；
• 这一步相当于用一个独立文件，把“要改什么、为啥这么改”说清楚。

3). Apply（实现） + Archive（归档）

完成并通过评审后：

openspec apply <proposal-id>

或在 Cursor：

/openspec:apply

• AI 根据提案内容改代码、写测试、更新文档；
• 上线后再执行 archive，把这次变更归档。

简写就是：

提案 → 审查 → 实现 → 归档

4. 相对 Spec‑Kit 的差异

对比起来：

• Spec‑Kit 更像“完整的工程流程模板”，适合新项目从零起步；
• OpenSpec 更像“变更管理中枢”，擅长在已有项目上做小步快跑。

OpenSpec 的典型优势：

• 命令和概念更少，上手快；
• 对已有代码库更友好，每次改动都是一个独立的 Proposal；
• 规格与变更可以在 Cursor、Claude Code 等多种工具中共用。

四、在 Cursor 中使用 Spec‑Kit 与 OpenSpec

Cursor 作为一个 AI IDE，本身支持：

• .cursor/rules：为项目配置长期规则和上下文；
• Slash Commands：在聊天输入 /xxx 调用预设流程；
• Plan / SDD 模式：内置计划视图。

Spec‑Kit 和 OpenSpec 都是通过 给 Cursor 注入一组 Slash 命令和对应 Prompt 来工作的。

1. 在 Cursor 中使用 Spec‑Kit（适合新项目）

两种常见方式：

方式 A：直接用 CLI + Cursor

1). 终端安装并初始化 Spec‑Kit

使用 uv 安装 Spec-Kit：

# 安装 uv，需要本地已安装 Python
pip install uv

# 使用 uv 从 github 仓库安装 spec-kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 若需更新最新版本，增加 --force 参数即可：
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

# 查看帮助信息
specify --help

# 检查支持的工具列表的安装状态
specify check

在当前项目中初始化：

# initialize in existing project
specify init . --ai cursor-agent
# or
specify init --here --ai  cursor-agent

# Check installed tools
specify check

2). 在 Cursor 聊天中输入：

/speckit.constitution
/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.implement

3). 按顺序推动项目：先宪法，再规格，再计划，再任务，最后实现与审查。

方式 B：用社区封装的 Cursor Toolkit

• 克隆类似 spec-kit-command-cursor 这类社区仓库；
• 把里面的 .cursor/rules 配置到自己的项目中；
• 之后在 Cursor 输入 /spec... 系列命令即可。

什么时候用？

• 新项目 / 新微服务从零搭建；
• 需要团队共同维护“宪法”和“规格”；
• 对流程和质量要求较高的场景（如金融、医疗、政府等）。

2. 在 Cursor 中使用 OpenSpec（适合迭代现有项目）

基本使用步骤：

1). 安装并初始化：

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

openspec init   # 交互中选择 Cursor 作为主要 AI 工具之一

2). 初始化后会生成 openspec/ 目录，以及一组可在 Cursor 中用的 Slash 命令：

• /openspec:proposal
• /openspec:apply
• /openspec:archive

3). 实际使用示例：

提案：

/openspec:proposal "Add passwordless login by email link"

• 在 changes/xxx-passwordless-login.md 中和 AI 一起把需求写清楚；

确认后：

/openspec:apply

让 AI 按提案修改代码、测试和文档；

上线后：

/openspec:archive

什么时候用？

• 已经有相当体量的代码库；
• 主要是做新需求、新接口、小重构和 Bug 修复；
• 希望让每次改动都有一份可审计的“变更说明”，又不想上来就套一整套重流程。

五、在 Cursor/AI IDE 场景下如何选型？

可以从两个维度做决策：场景和控制力度。

1. 按使用场景划分

• 0→1 新项目 / 大型重构
  建议优先用：Spec‑Kit + Cursor
  • 把“宪法、规格、计划、任务”一次性搭好；
  • 团队可以围绕这些文件讨论和评审；
• 1→n 增量迭代 / 老系统小步重构 / 个人项目
  建议优先用：OpenSpec + Cursor
  • 每次改动都对应一个 Proposal，轻松上手；
  • 不必为一个小需求跑完整的 Spec‑Kit 全流程。

2. 按工程控制力 vs 敏捷性

• 更看重流程和质量控制
  • 选 Spec‑Kit：
  • 更像一整套工程方法论；
  • 好处是“不会少做步骤”，坏处是“有时略重”。
• 更看重节奏和试错效率
  • 选 OpenSpec：
  • 从“把这一次改动说清楚”开始；
  • 可以逐步演进，不一次性上重流程。

六、给团队与个人的落地建议

1. 团队 / 公司

建议按“先试点、再推广”的方式推进：

1. 双轨试点
   • 在一个新项目上试用 Spec‑Kit + Cursor；
   • 在一个老项目上试用 OpenSpec + Cursor；
   • 对比：需求澄清时间、返工次数、PR 规模、缺陷率等。
2. 统一规格模板
   • 抽象出团队统一的规格结构：背景、场景、输入输出、边界、验收标准；
   • Spec‑Kit 的 spec.md 和 OpenSpec 的 specs/ / changes/ 都用这一套结构。
3. 把规格接入 PR 流程
   • 要求：每个功能 PR 必须在描述中附上对应的规格或 Proposal 链接；
   • 评审时先看规格，再看代码。

2. 个人 / 小团队

建议从简单的开始：

1. 先用 OpenSpec + Cursor
   • 以后每次要做“一个功能 / 一次 Bug 修复”，先写 Proposal 文件；
   • 再用 /openspec:apply 让 Cursor 按 Proposal 来改代码。
2. 感觉项目越来越复杂时，再引入 Spec‑Kit
   • 若你开始频繁思考“架构边界”“约束”“非功能性需求”等问题；
   • 就可以用 Spec‑Kit 生成 CONSTITUTION.md 和更完整的 spec.md、plan.md、tasks.md。

七、总结

• SDD 的核心是：“规格先行，让规格成为唯一真相”，用来约束 AI 编码，避免氛围编程。
• Spec‑Kit 提供一套完整、偏“工程化流程”的工具链，非常适合 0→1 新项目和需要强控制力的团队场景。
• OpenSpec 更轻量、灵活，特别适合在已有项目中小步引入 SDD，把每次变更收敛成一个清晰的 Proposal。
• 在 Cursor 中，两者都通过 Slash 命令深度集成，可以把“想清楚 → 写清楚 → 让 AI 按规格执行”变成日常开发流程的一部分。