我的 OpenSpec 入门之旅：从零到理解 AI 原生开发工作流

这篇博客记录了我在 Cursor IDE 中第一次使用 OpenSpec 的完整体验。从一无所知到完成第一个变更周期，再到深入理解其设计哲学，所有的问题和答案都在这里。

---

一、初体验：完成第一个 OpenSpec 周期

1.1 起步：选一个任务

我的项目是一个空目录，连 src/ 都没有。于是我选择了一个最基础的任务——初始化一个 3D 点云对比项目的骨架。

OpenSpec 的入门命令 /opsx-onboard 像一个引导教程，带我走完了整个流程。

1.2 创建变更 (Change)

第一步是在终端执行：

openspec new change "init-point-cloud-project"

这会在 openspec/changes/ 下创建一个以任务命名的文件夹，里面自带四个空文件/目录：

openspec/changes/init-point-cloud-project/
├── proposal.md    ← 为什么要做这件事
├── design.md      ← 怎么做
├── specs/         ← 具体的、可测试的需求
└── tasks.md       ← 执行步骤清单

1.3 逐步填写工件 (Artifacts)

AI 引导我依次完成了四个工件：

Proposal (提案)：捕捉意图。

“我们需要初始化 3D 点云对比项目的骨架，以便团队可以开始开发点云加载、可视化和对比功能。”

Specs (规格)：用 WHEN/THEN/AND 格式定义可测试的需求。

• WHEN the project is initialized
• THEN the src/ directory exists
• AND the data/ directory exists

Design (设计)：记录技术选型和权衡。

我们选择 Open3D 作为主要的点云处理库，因为它易于使用、文档丰富且性能良好。
Alternative: PCL（功能强大但 Python 绑定较复杂）。

Tasks (任务)：分解为可执行的 CheckList。

• 1.1 Create directory structure (src, data, tests)
• 1.2 Create README.md with project description
• 2.1 Create requirements.txt with Open3D and Numpy
• 3.1 Create src/main.py with basic entry point logic

1.4 实施与归档

AI 按照 tasks.md 逐一实现，每完成一项就勾选。最后执行归档：

openspec archive "init-point-cloud-project"

归档做了两件事：

1. 将 changes/init-point-cloud-project/ 移入 changes/archive/2026-02-07-init-point-cloud-project/。
2. 将变更中的 Specs 合并到了主目录 openspec/specs/project-skeleton/spec.md。

第一个完整周期就此完成。

---

二、深入理解：目录结构全解

完成第一个周期后，我的第一个问题是：这些文件夹到底是干什么的？

2.1 三大区域

OpenSpec 的文件夹结构将"施工现场"、"系统现状"和"历史记录"完美分离：

openspec/
├── changes/                  ← 【施工现场】正在进行的工作
│   └── <change-name>/        ← 一个具体的变更任务容器
│       ├── proposal.md       ← 提案 (Why & What)
│       ├── design.md         ← 设计 (How)
│       ├── tasks.md          ← 任务清单 (Action Plan)
│       └── specs/            ← 变更规格 (Delta Specs)
│
├── specs/                    ← 【真理之源】系统的当前状态
│   └── <capability>/         ← 按功能模块分类的规格
│       └── spec.md           ← 具体的规格文件
│
└── changes/archive/          ← 【历史档案馆】已完成工作的记录
    └── YYYY-MM-DD-<name>/    ← 归档的变更快照

• changes/：所有新工作从这里开始，做完了就清走。
• specs/：系统当前具备的所有能力的"活文档"。新成员（或新的 AI 会话）只需看这里，就能了解系统全貌。
• archive/：决策历史。“为什么我们当初选了 Open3D？”——去翻 archive/ 里的 design.md 就知道了。

2.2 Delta Specs vs. Main Specs：最精妙的设计

我注意到 spec.md 在两个地方出现了：changes/.../specs/ 和 openspec/specs/。它们有什么不同？

特性	Delta Specs (changes/ 下)	Main Specs (specs/ 下)
状态	Draft（草稿/拟议中）	Live（生效中/已发布）
含义	“我希望系统变成什么样”	“系统现在是什么样”
生命周期	随变更创建，归档时合并后消失	永久存在，随项目演进
Git 类比	Feature Branch（功能分支）	Main Branch（主分支）
作用	指导 AI 完成本次任务	指导 AI 理解现有系统全貌

数据流向：开发时写在 changes/ → 归档时 CLI 自动合并到 specs/ → changes/ 文件夹移入 archive/。

2.3 为什么 Main Specs 只保留 spec.md？

你可能会好奇：changes/ 里有四个文件（proposal、specs、design、tasks），为什么归档后 openspec/specs/ 里只留下了 spec.md 这一个？

因为这四个工件本质上分属两类：

A 类：描述"过程"（临时的，做完就没用了）

文件	回答的问题	做完之后…
proposal.md	为什么要做这件事？	动机已经实现了，不需要反复看
design.md	怎么做？技术方案是什么？	代码本身就是"怎么做"的答案
tasks.md	步骤是什么？做到哪了？	全部勾完了，清单就废了

B 类：描述"系统"（永久的，必须一直维护）

文件	回答的问题	做完之后…
specs/spec.md	系统能做什么？行为标准是什么？	这个能力永远存在，必须持续记录

打个比方：想象你在装修房子——

• Proposal：“我要把客厅刷成白色，因为现在的黄色太暗了。” —— 装完后，你不需要在墙上贴"我为什么刷白色"。
• Design：“用立邦漆，刷两遍底漆一遍面漆。” —— 装完后，你不需要在墙上贴"我用了什么漆"。
• Tasks：“第一步铲墙皮，第二步刷底漆…” —— 装完后，清单扔掉。
• Spec：“客厅墙面颜色：白色。” —— 这个必须永远记着！ 因为下次装修时，工人需要知道现在是什么颜色，才能决定下一步怎么改。

所以归档时：

• proposal.md、design.md、tasks.md → 全部进入 archive/（历史记录，只用来追溯"当时为什么这么做"）。
• specs/spec.md → 合并进 openspec/specs/（活文档，用来告诉所有人"系统现在能做什么"）。

Main Specs 就像产品的"功能说明书"——你买一台洗衣机，说明书只告诉你"它能洗什么、怎么操作"，不会告诉你"工程师当时为什么选了这个电机"。这就是为什么 specs/ 里只需要 spec.md，因为它是唯一具有持久价值的工件。

---

三、CLI 与 Agent：两种命令的底层关系

3.1 角色分工

• CLI (openspec ...)：底层的命令行工具，只懂文件操作。类似 git。
• Agent (/opsx:...)：Cursor 的 AI 代理脚本，拥有智能。它是 CLI 的"驾驶员"。

3.2 调用链路

当你在对话框输入 /opsx:new "login" 时，背后发生了什么：

你（用户）
  ↓  输入 /opsx:new "login"
Agent（AI 大脑）
  ↓  思考意图，决定创建变更
  ↓  执行终端命令：openspec new change "login"
CLI（机械臂）
  ↓  在硬盘上创建目录结构
Agent（AI 大脑）
  ↓  看到目录创建好了
  ↓  开始引导你写 Proposal、Specs、Design、Tasks

结论：你 → 指挥 Agent → Agent 指挥 CLI。日常开发中 90% 的时间用 Agent 命令，10% 的时间用 CLI 命令（查看状态或手动修正）。

---

四、命令速查与使用场景

4.1 完整命令对照表

Agent 命令	对应的 CLI 操作	使用场景
/opsx:explore	无（纯 AI 思考）	想法模糊，需要分析代码、讨论方案
/opsx:new "name"	openspec new change "name" + AI 引导写文档	新手或复杂任务，需要一步步推敲
/opsx:ff "name"	openspec new change "name" + AI 一次性生成所有文档	老手或简单任务，追求速度
/opsx:continue "name"	无（AI 读取现有文件继续工作）	昨天做了一半，今天继续
/opsx:apply "name"	无（AI 读取 tasks.md 并修改代码）	文档写好了，开始写代码
/opsx:verify "name"	openspec validate "name" + AI 检查代码	写完代码，验证是否符合 Spec
/opsx:archive "name"	openspec archive "name"	任务完成，归档并合并 Specs

4.2 工作流程图

  ┌─────────────┐
  │  模糊的想法   │
  └──────┬──────┘
         ↓
  /opsx:explore  ← 思考阶段（可选）
         ↓
  ┌──────┴──────┐
  │  明确要做什么  │
  └──────┬──────┘
         ↓
  /opsx:new 或 /opsx:ff  ← 定义阶段
         ↓
  ┌──────────────────────┐
  │ Proposal → Specs →   │
  │ Design → Tasks       │
  └──────┬───────────────┘
         ↓
  /opsx:apply  ← 执行阶段
         ↓
  ┌──────┴──────┐
  │  代码写完了   │
  └──────┬──────┘
         ↓
  /opsx:verify  ← 验证阶段（可选）
         ↓
  /opsx:archive  ← 完成阶段
         ↓
  ┌──────────────────────────┐
  │ Delta Specs → Main Specs │
  │ Changes → Archive        │
  └──────────────────────────┘

---

五、高级技巧

5.1 多变更并行开发

openspec/changes/ 下可以同时存在多个文件夹（如 feature-A 和 fix-B）。但要注意：

• 不冲突时（改不同文件）：直接切换即可。
• 冲突时（改同一文件）：必须配合 Git 分支。Branch A 对应 Change A，Branch B 对应 Change B。

5.2 暂停与恢复

OpenSpec 的"暂停"不是一个命令，而是一个逻辑概念——因为所有进度都保存在文件里，你只需"放下这个文件夹，拿起那个"。

标准操作流：

1. git stash（保护半成品代码）
2. /opsx:ff "hotfix-bug"（创建紧急修复）
3. 修复 → /opsx:archive "hotfix-bug"
4. git stash pop（恢复现场）
5. /opsx:continue "feature-A"（继续之前的任务）

5.3 Cursor IDE vs. Claude Code CLI

场景	Cursor IDE (GUI)	Claude Code (CLI)
探索 & 规划	文件树 + 分屏，全局视野强	纯文本，依赖记忆
审查文档	可视化 Diff，直观高效	只能看文本输出
自动编码	需要频繁确认	可以自主循环执行
适合阶段	定义 + 审查	批量执行

结论：Cursor 是"指挥塔"，Claude Code 是"无情的编码机器"。OpenSpec 本质上是管理决策的系统，Cursor 更般配。

---

六、OpenSpec 与 CLAUDE.md 的关系

看过 Tony Bai 的《AI 原生开发工作流实战》后，我意识到 OpenSpec 并不是孤立存在的。它和 CLAUDE.md（或 Cursor 的 .cursor/rules）解决的是两个维度的问题：

• CLAUDE.md：静态的"员工手册"。告诉 AI 公司的代码风格、技术栈版本、日志规范。不管做什么任务，这些规则都得遵守。
• OpenSpec：动态的"项目施工单"。告诉 AI 这次具体要改什么业务逻辑，分几步走。任务完成了就归档。

两者是互补的：CLAUDE.md 规范了代码的形，OpenSpec 定义了代码的神。

最佳实践是两者结合：在项目根目录放一个 CLAUDE.md（或 .cursor/rules/）来定义代码风格，然后用 OpenSpec 来管理每一个具体的开发任务。

---

七、总结

经过这次完整的入门体验，我对 OpenSpec 的理解可以浓缩为一句话：

OpenSpec 的本质是将"隐性的思维过程"转化为"显性的文档资产"。

它让 AI 不再是"黑盒"，而是可控的"白盒"。它让你的项目不再只有代码，还有完整的决策历史 (archive/) 和功能说明书 (specs/)。

下次开始工作前，请记住：不要直接写代码，先 /opsx:ff！

---

本文基于 2026 年 2 月 7 日在 Cursor IDE 中使用 OpenSpec 的实际操作记录整理而成。