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

我的 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"

归档做了两件事：

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

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

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

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/。它们有什么不同？

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

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

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

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

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

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

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

• 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 完整命令对照表

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

标准操作流：

5.3 Cursor IDE vs. Claude Code CLI

结论：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 的实际操作记录整理而成。