发展历史
全称:spec-driven develop,spec 是 specification 的缩写,代表规范,我们以 OpenSpec 这个库为例。
CLI 基础使用
项目初始化 (Setup)
-
openspec init -
作用:在当前目录下初始化 OpenSpec。
-
行为:
-
创建
.openspec/或openspec/目录结构。 -
生成
project.md(项目上下文)和AgentS.md(AI 说明书)。 -
询问你使用的 AI 工具(Cursor, Copilot 等)并生成对应的配置文件。
-
何时用:刚把 OpenSpec 引入项目时。
-
openspec update -
作用:更新 OpenSpec 的配置和 Agent 文档。
- 行为:如果你升级了
npm包,或者想重新生成AGENTS.md,运行此命令。它会确保你的 AI 提示词是最新的。 - 何时用:感觉 AI 变笨了,或者升级了 OpenSpec 版本后。
日常开发流 (Workflow)
-
openspec list -
作用:列出当前所有“进行中”的变更(Active Changes)。
- 显示:会显示变更 ID(Change ID)、状态、以及
tasks.md里的任务完成进度(例如[2/5])。 - 何时用:想知道现在有哪些活儿没干完时。
-
参数:
-
--specs: 列出已归档的 Specs(查看现在的系统“真理”)。 -
openspec show <change-id> -
作用:输出某个变更的详细信息(通常以 JSON 格式)。
- 行为:这个命令主要是给 AI 看的。当 AI 需要读取某个 Spec 的全部细节时,它会在后台运行这个命令。
-
参数:
-
--json: 强制输出 JSON 格式。 -
--deltas-only: 只看变更的部分。 -
openspec view(部分版本支持) -
作用:启动一个终端内的可视化界面(TUI)。
- 行为:以更图形化的方式展示任务进度条。
质量控制 (Quality Control)
-
openspec validate <change-id> -
作用:检查你的 Spec 文档格式是否标准。
-
行为:它会检查:
-
Markdown 的 Frontmatter 是否正确。
tasks.md里是否有未完成的任务。-
proposal.md结构是否完整。 -
参数:
-
--strict: 开启严格模式,任何小格式错误都会报错(推荐 AI 使用)。
结束与归档 (Finish)
-
openspec archive <change-id> -
作用:将一个变更“合并”到主 Specs 库中。
-
行为:
-
把
changes/<id>目录移动到changes/archive/<id>。 -
关键动作:把该变更中
spec.md的内容,合并/更新到openspec/specs/目录下的长期文档中。 -
参数:
-
--yes/-y: 自动确认,不询问(AI 自动执行时通常带这个)。
其他 (Utility)
-
openspec version -
查看当前安装的版本。
-
openspec help -
查看帮助文档。
💡 核心区别:CLI 命令 vs. AI 指令
初学者容易混淆 终端命令 和 Cursor 斜杠命令,它们的关系如下:
总结:
- AI (Prompt) 负责:创造(写文档、写代码)。
- CLI (Terminal) 负责:管理(初始化、列出、验证、移动文件)。
平时你最常用的 CLI 命令应该只有两个:openspec list (看进度) 和 openspec update (维护)。其他的通常都由 AI 代劳了。
目录结构
一看这个 spec的描述是不是很像我们要求的系分文档?从我的角度上看,他比系分更全面,也更符合当前的实际开发流程。
openspec/├── project.md # Project conventions├── specs/ # Current truth - what IS built│ └── [capability]/ # Single focused capability│ ├── spec.md # Requirements and scenarios│ └── design.md # Technical patterns├── changes/ # Proposals - what SHOULD change│ ├── [change-name]/│ │ ├── proposal.md # Why, what, impact│ │ ├── tasks.md # Implementation checklist│ │ ├── design.md # Technical decisions(optional; see criteria)│ │ └── specs/ # Delta changes│ │ └── [capability]/│ │ └── spec.md # ADDED/MODIFIED/REMOVED│ └── archive/ # Completed changes
系分存在的问题
- 工期紧张下无法考虑周全;
- 在实际开发中可能存在变动,但系分已经过时;
- 作为一个研发标准,对研发更多是一种负担?(OS:我已经想清楚了,为什么还要我写个文档)毕竟大部分人都不爱写很规范的文档。
为什么我们又开始重视它
大家应该都知道,在目前这个阶段,claude 写的代码足以覆盖任何我们碰到的场景(或者对我来说足够了),我们原先的旧有的提效方式,组件库、动态表单、低代码搭建,他是稳定的提效方案,但对于 AI 来说,他们具有的上手成本、研发体验也都是负担。对于 AI 来说,如果都是开源的内容,他一天就可以帮我构建出一个系统,在旧有的提效方案上仍然不是一个级别。
但 AI 存在上下文窗口限制导致的幻觉;不理解项目规范、旧有实现,变更都在破坏旧有结构;代码 review 的负担(我一直觉得这是一个伪命题,你除非自己已经在脑子中完全构建了一遍细节,要不然怎么可能能发现一些细节的问题)。
所以社区又重新开始用它来作为 AI 辅助编程的一种开发范式,之前是 TDD,通过测试来保证,因为我们只用对功能负责,如果他的功能是正常的,那实现复杂一些或者丑陋一些是历史债务,总会有个幸运儿来接手的,或者我们称他为 AI 善后工程师。
解决一个 bug 的最好时机永远是引入的阶段,所以 TDD 这种后驱黑盒的方式并不能给你带来安全感。因为你知道实际你在把赌注押在 AI 没有幻觉。但很可惜他有。
传统的 SDD 之所以让人讨厌,是因为写 Spec 的是人,写 code 的也是人。
因为 AI 把我们的生产关系变了,现在写 spec 的是 AI,review 的是人,写 code 的还是 AI,我们从 review 代码变成了 review 设计。
实际需求
我们来看一个待开发的的目录结构和文件。
./├── proposal.md // 代表的是我们的草案内容,他里面存放的是我们给到 LLM 的需求总结。├── specs│ └── artifact-notification│ └── spec.md // 我们事实对应的规格文件└── tasks.md // 拆分的任务 TODO LIST
## Change: 移动端支持 PPT 大纲生成完成通知## Why目前 PC 端已实现在 PPT 大纲生成完成时的全局通知功能,但在移动端该功能被明确禁用。为了提供一致的用户体验,需要在移动端也支持该通知,但考虑到移动端屏幕尺寸和交互习惯,需要采用底部的 Snackbar 样式而非 PC 端的右上角通知。## What Changes- 修改 `showPPTOutlineNotification` 逻辑,移除对移动端的禁用限制。- 新增移动端专用的 Snackbar 通知组件/样式。- 移动端通知显示在页面底部。- 移动端通知内容和交互逻辑("去查看"按钮)与 PC 端保持一致。## Impact- **Affected Specs**: `artifact-notification`- **Affected Code**: - `src/xxx/Chat.tsx` - 新增 Mobile Snackbar 组件 (待定位置,可能在 `src/components` 或就在 `Chat.tsx` 内部实现)
## 1. Implementation- [x] 1.1 设计并实现移动端 Snackbar 组件 - [x] 1.1.1 创建 MobileSnackbar 组件 (或复用现有组件库的类似组件) - [x] 1.1.2 实现底部弹出动画和样式 - [x] 1.1.3 支持自定义内容和操作按钮- [x] 1.2 修改通知触发逻辑 - [x] 1.2.1 在 `xxx.tsx` 中修改 `showPPTOutlineNotification` - [x] 1.2.2 移除 `if (isMobileDevice()) return;` 判断 - [x] 1.2.3 根据设备类型分发不同的通知展示方式 (PC 使用 `notification.info`, Mobile 使用新 Snackbar)- [] 1.3 验证与测试 - [] 1.3.1 验证移动端触发时机是否正确 - [] 1.3.2 验证移动端样式是否符合设计 (底部 Snackbar) - [] 1.3.3 验证"去查看"按钮在移动端是否正常工作
## MODIFIED Requirements### Requirement: PPT 大纲生成完成通知系统 SHALL 在检测到智能体中断并首次生成 PPT 大纲时,如果用户当前未选中该产物,自动显示通知提醒用户。#### Scenario: 触发通知显示- **GIVEN** 用户在使用智能体对话(PC 端或移动端)- **AND** 系统接收到中断消息- **AND** 用户当前选中的内容不是该产物- **WHEN** 系统处理中断消息完成- **THEN** 系统显示一个通知- **AND** PC 端显示为右上角全局通知,移动端显示为底部 Snackbar 通知- **AND** 通知标题为"大纲生成完成"- **AND** 通知内容为"{产物名称} 大纲内容已生成,请确认大纲内容"- **AND** 通知包含一个"去查看"按钮- **AND** 通知不会自动关闭(需要用户手动关闭)#### Scenario: 点击"去查看"按钮- **GIVEN** PPT 大纲生成完成通知已显示- **WHEN** 用户点击通知中的"去查看"按钮- **THEN** 系统调用 `xxx` 方法- **AND** 传入参数包含: - `id`: 当前产物的 artifactId- **AND** 工作面板切换到所有文件面板并选中对应产物- **AND** 通知自动关闭#### Scenario: 移动端显示底部 Snackbar 通知- **GIVEN** 用户在移动端使用智能体对话- **AND** 触发了 PPT 大纲生成完成通知- **WHEN** 通知显示时- **THEN** 通知以 Snackbar 形式出现在屏幕底部- **AND** 样式区别于 PC 端通知,适配移动端屏幕#### Scenario: 用户已选中该产物时不显示通知- **GIVEN** 用户在 PC 端或移动端使用智能体对话- **AND** 智能体处于中断状态并生成了 PPT 大纲- **AND** 用户当前选中的内容就是该产物- **WHEN** 组件检测到 `canEdit` 状态变化- **THEN** 系统不显示通知#### Scenario: 避免重复通知- **GIVEN** PPT 大纲生成完成通知已经显示过一次- **WHEN** 组件重新渲染但 `canEdit` 状态未发生实际变化- **THEN** 系统不再重复显示通知
``集成 IDE 使用
cursor 对 openspec 进行了天然的支持,开箱即用。
其他支持自定义命令的可以通过配置自定义命令来实现,提示词咱主打一个直接借鉴(先抄一版 cursor的)。
知易行难
重复需求未被检测到
场景:多人协作或者新人加入时,他想开发一个功能,其实已经在归档里已经有了,但是他输入后仍然触发了新的需求。
Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code ordocs(e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
通过 openspec-propoasl进行已归档需求测试时,他并没有想象的那么美好,我尝试了两个 AI IDE 都帮我重新生成了一份文档,问题出在哪里?LLM(大模型)Prompt 工程与 IDE 实际执行能力之间的鸿沟。
我们来看他提示词里 steps,第一步他描述了 review openspec 下的内容,但是他是通过 run xxx 这依赖agent 的终端执行能力,如果因为一些原因失败了,他又会给你生成一份新的了。
- 他觉得他执行了,但实际没执行(非 agent 模式)
- 他执行了,他失败了
解法:
问题的核心是因为,openspec 本身是一个 cli 命令工具,cursor 似乎也对自己的命令执行很有自信,但真实的环境总是复杂的,就像软件总会有 bug 一样。
那我们就把命令执行的方案改为依赖 IDE 目前的 codebase,让他强制总是先去读目录下的文件(我们已经在最终完整版的命令里添加,这里不再赘述相关代码)。
草案生成后如何修改
直接使用修改对应的文件。
我们可以看到无论是 cursor 天然支持的命令还是他自己的 CLI 好像都没有提供 update 这个场景。
官方针对这个没有任何说明, AI 给了我一个回答,感觉也合理。
这是一个非常深刻的产品设计问题。你没看错,**OpenSpec 的设计哲学里确实故意“遗漏”了 `update` 这个动作。**这并不是开发者忘了做,而是基于 **“文档即真理(Docs as Code)”** 和 **“不可变历史”** 这两个核心设计理念。以下是为什么没有 `/openspec-update` 的 4 个核心原因:### 1. 哲学原因:编辑文档不需要“命令”OpenSpec 把 Markdown 文档看作是**代码**的一部分。* **类比 Git**:你在修改代码逻辑时,需要运行 `git update-code` 吗?不需要。你直接打开文件编辑,然后保存。* **OpenSpec 逻辑**: * 如果你想改需求,直接打开 `spec.md` 改文字。 * 如果你想改计划,直接打开 `tasks.md` 改列表。 * **“修改”是编辑器的基础功能,不是 CLI 的功能。**引入一个 `/openspec-update` 命令反而会显得多余:因为 AI 的修改本质上就是“读取文件 -> 覆写文件”,这在自然语言对话中(“把登录改成支持手机号”)已经涵盖了。### 2. 流程原因:Proposal 包含了 Update在 OpenSpec 的定义里,**Proposal(提案)是一个持续迭代的过程**,而不是一次性的动作。* **第一次运行 `/openspec-proposal`** = 从 0 到 1 创建文档。* **第二次运行 `/openspec-proposal`** = 基于现有文档进行修改(迭代)。在 Cursor 的 Prompt 逻辑里,`/openspec-proposal` 的定义其实包含了“Review gaps”和“Draft spec deltas”。如果你对 AI 说:“**`/openspec-proposal` 之前的方案太复杂了,简化一下**”,AI 会直接修改现有的文件。**所以在 AI 看来,Create 和 Update 是同一个能力的两个面。**### 3. 架构原因:避免“状态地狱”如果引入了 `update` 命令,就会带来状态管理的复杂性:* “我是要在 `apply` 之前 update,还是之后 update?”* “Update 是重置任务,还是保留进度?”OpenSpec 选择了最简单的路径:* **没有状态锁**:文件随时可改。* **执行驱动**:`/openspec-apply` 永远只看**当前这一刻**的 `tasks.md`。不管你是刚生成的,还是手动改了 100 次的,Apply 只负责执行当下。### 4. 归档逻辑:已完成的不可 Update对于已经 **Archive(归档)** 的需求,OpenSpec **严禁**使用 `update`。* **历史不可篡改**:归档等于“合同已结案”。* **新变更**:如果你要改旧功能,必须发起一个新的 `new` (Proposal)。* **CLI 里的 `openspec update`**: * 注意,CLI 确实有一个 `openspec update` 命令,但它的作用是**更新 `AGENTS.md` 和配置文件**(升级库本身),而不是更新你的业务 Spec。---### 最佳实践:当你真的想 "Update" 时该怎么办?虽然没有这个命令,但在实际操作中,你可以通过以下三种方式达成 "Update" 的目的:#### 方式 A:手动修改(最推荐,最快)直接在编辑器里打开 `openspec/changes/xxx/spec.md`,删掉不想要的,加上想要的。* *优势*:人类改文档比跟 AI 废话要快得多,且精准。#### 方式 B:复用 Proposal 命令直接再次输入:> `/openspec-proposal` 需求有变,请把数据库改成 MongoDB,并更新 spec 和 tasks。* *效果*:AI 会覆写当前目录下的文档。#### 方式 C:在 Apply 时“挟持”在执行前临时变卦:> `/openspec-apply` **注意:在执行前,请先更新 tasks.md,去掉所有关于 Redis 的步骤。**### 总结**OpenSpec 没有 `update`,因为 Markdown 文件本身就是可变的接口。**它鼓励你:1. **Draft** (起草/迭代) -> 复用 `/openspec-proposal` 或直接编辑。2. **Apply** (执行) -> 照着文档做。3. **Archive** (归档) -> 封存,下次再来请开新单。这种“少即是多”的设计,反而避免了在复杂的命令参数中迷路。
他提供的核心能力其实是文档管理功能,而文档本身就是可编辑的。考虑极端一些的场景,他其实只是给我们对已有功能进行归档。我如果抛开 AI,他的逻辑也是成立的,只是他的存在正好可以让大模型从搜索代码到先搜索总结后的功能。
手动进行修改是他的哲学设计,但基于此也会延伸出来一个问题。
没有特殊的 prompt 约束,模型并不知道一个 change 下的文件是需要联动更新的,但是实际上他们是依赖关系。
我们还是需要自定义一个 openspec-update 命令,来处于需求变更的场景,让 prompt 只专注在修改changes 下的文件内容。当用户调用它时,他会查询当前还未归档的变更,如果存在多个需要跟用户手动确认是作用于哪一个变更。(我们已经在最终完整版的命令里添加,这里不再赘述相关代码)
当我们运行归档时,他怎么知道要归档到哪里
我们回看标准目录,其实答案已经藏在那里。他是通过 changes/[change-name]/specs/[capability]的capability 来决定的,如果你发现有问题,因为这个不涉及到文件的联动更新,直接手动修改即可。
归档错误
我在执行一次之前归档需求的优化时碰到了报错
MODIFIED failed for header "### Requirement…