【AI 】OpenSpec 实战指南：在 Cursor 中落地 AI 原生开发工作流
OpenSpec 实战指南：在 Cursor 中落地 AI 原生开发工作流
前言：OpenSpec 是“规范驱动开发 (Spec-Driven Development, SDD)”在 Cursor IDE 中的最佳实践落地。它将 AI 从一个“容易遗忘的编码助手”升级为“严谨的工程合作伙伴”。
0. 安装和初始化
安装要求：Node.js >= 20.19.0
npm install -g @fission-ai/openspec@latest
openspec --version 装好后可以查看版本，输出版本号，说明安装成功，我的版本号是1.1.1，注意1.0.0之后的版本命令都更新了，我讲的都是新的命令。
选择你的工程目录，打开cmd输入，openspec init 初始化目录，
我这里用的是cursor，所以选择cursor。
确认后，显示如下：
这样整个工程就创建好了~~~~
1. 核心架构解密：CLI 与 Agent 的关系
在 OpenSpec 中，我们经常看到两类命令：openspec ... 和 /opsx:...。理解它们的底层关系，是你掌握这套系统的关键。
1.1 角色定义
- CLI (
openspec ...) —— “机械臂” (The Engine)- 本质：它是底层的命令行工具（类似于 Git 或 NPM）。
- 能力：它只懂文件操作。它负责创建文件夹、移动文件、验证 JSON 格式、合并文档。它没有智能，不理解业务，只听死命令。
- 运行位置：Terminal (终端)。
- Agent (
/opsx:...) —— “大脑” (The Brain)- 本质：它是 Cursor 的 AI 代理脚本（Prompt Chain）。
- 能力：它拥有智能。它负责思考架构、编写文档、生成代码。
- 运行位置：Chat (对话框)。
1.2 底层调用关系
Agent 是 CLI 的“驾驶员”。
当你输入 /opsx:new "login" 时，实际上发生了一连串的连锁反应：
- Agent 思考：AI 先分析你的意图，决定需要创建一个名为
login的变更。 - Agent 调用 CLI：AI 在后台默默执行了终端命令
openspec new change "login"。 - CLI 执行：CLI 在硬盘上创建了目录结构。
- Agent 接管：AI 看到目录创建好了，开始引导你：“好了，文件夹建好了，我们来写 Proposal 吧…”。
结论：你（用户）指挥 Agent，Agent 指挥 CLI。Agent 封装了繁琐的 CLI 操作，让你专注于业务逻辑。
2. 双重规格系统：Delta Specs vs. Main Specs
这是 OpenSpec 最精妙的设计之一。你会发现有两个地方存放 spec.md，它们看似相同，实则作用完全不同。
2.1 位置对比
- 位置 A (Delta Specs):
openspec/changes/<change-name>/specs/... - 位置 B (Main Specs):
openspec/specs/...
2.2 深度解析
| 特性 | Delta Specs (位置 A) | Main Specs (位置 B) |
|---|---|---|
| 中文名 | 变更规格 (拟议) | 主规格 (真理之源) |
| 状态 | Draft (草稿/拟议中) | Live (生效中/已发布) |
| 含义 | “我希望系统变成什么样” | “系统现在是什么样” |
| 生命周期 | 随变更创建，归档即消失 (合并) | 永久存在，随项目演进 |
| Git 类比 | Feature Branch (功能分支) | Main Branch (主分支) |
| 作用 | 指导 AI 完成本次开发任务 | 指导 AI 理解现有系统能力，帮助新成员上手 |
2.3 数据流向
- 开发时：你在
changes/下编写 Delta Specs。此时，它可能与 Main Specs 冲突（因为你要修改现有功能）。 - 归档时 (
/opsx:archive)：CLI 会自动将 Delta Specs 合并 (Merge) 到 Main Specs 中。 - 完成后：
changes/文件夹被移走，specs/文件夹更新为最新状态。
3. 标准工作流 (The Workflow)
第一阶段：思考 (Thinking)
- 指令：
/opsx:explore - 作用：自由探索，分析代码，不产生文件。
第二阶段：定义 (Defining)
- 指令：
/opsx:new "任务名"(新手向，一步步引导)/opsx:ff "任务名"(老手向，Fast-Forward，一次性生成)
- 产出工件：
- Proposal: Why & What (意图)。
- Specs (Delta): 具体的、可测试的需求 (WHEN…THEN…)。
- Design: 技术选型、架构决策。
- Tasks: 执行清单。
第三阶段：执行 (Executing)
- 指令：
/opsx:apply "任务名" - 作用：AI 读取
tasks.md，自动写代码。 - 技巧：中断后使用
/opsx:continue "任务名"恢复。
第四阶段：完成 (Finishing)
- 指令：
/opsx:archive "任务名" - 作用：
- 验证任务完成度。
- 将 Delta Specs 合并进 Main Specs。
- 将变更文件夹移入
archive/目录作为历史记录。
4. 最佳实践与 FAQ
4.1 并行开发与“暂停”
- 场景：正在做
feature-A，突然要修bug-B。 - 操作流：
git stash(保护feature-A的半成品代码)。/opsx:ff "bug-B"(创建修复任务)。/opsx:apply->/opsx:archive(修复并归档)。git stash pop(恢复现场)。/opsx:continue "feature-A"(继续之前的任务)。
4.2 为什么不用 Cursor (CLI)命令行？
- Cursor (CLI)：适合“盲写”和自动化执行，但缺乏全局视图。
- Cursor (IDE)：OpenSpec 产生大量文档，IDE 的文件树、分屏对比和Diff 视图能让你更好地进行决策和审查 (Review)。
- 建议：在 IDE 里做规划和 Review，享受掌控感。
4.3 什么时候该用什么命令？
- 90% 的时间：用
/opsx:...(Agent 命令)。让 AI 帮你干活。 - 10% 的时间：用
openspec ...(CLI 命令)。通常用于查看状态 (openspec status) 或手动强制归档。
5. 总结
OpenSpec 的本质是将**“隐性的思维过程”转化为“显性的文档资产”**。
- 它让 AI 不再是“黑盒”，而是可控的“白盒”。
- 它让你的项目不再只有代码，还有完整的决策历史 (
archive/) 和 功能说明书 (specs/)。
