Spec-Driven Development (SDD) 全称为 specification-driven development，即规范驱动开发。我们以 OpenSpec 这个开源库为例，探讨其在当前 AI 编程背景下的落地实践。
从上图可以看出，SDD 理念经历了从学术概念到工业标准，再到与 AI 结合复兴的完整历程。其核心在于，先通过人类与机器的共同语言（如 Markdown）清晰地描述业务逻辑与规范，再基于此进行开发。
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)
质量控制 (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：我已经想清楚了，为什么还要我写个文档）毕竟大部分人都不爱写很规范的文档。
为什么我们又开始重视它
大家应该都知道，在目前这个阶段，AI 写的代码足以覆盖很多业务场景。我们原先的旧有提效方式，如组件库、动态表单、低代码搭建，是稳定的提效方案，但对于 AI 来说，它们也具有上手成本和研发体验的负担。对于 AI 而言，如果都是开源的内容，它一天就可以帮我构建出一个系统，其效率远超旧有方案。
但 AI 存在上下文窗口限制导致的“幻觉”问题；不理解项目规范、旧有实现，变更容易破坏原有结构；代码 Review 的负担也随之而来（我一直觉得这是一个伪命题，除非你已经在脑中完全构建了一遍细节，否则很难发现一些隐蔽问题）。
所以社区又重新开始用 SDD 来作为 AI 辅助编程的一种开发范式。之前是 TDD，通过测试来保证功能正确。但解决一个 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
proposal.md 示例：
# 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` 内部实现)
tasks.md 示例：
## 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 验证“去查看”按钮在移动端是否正常工作
spec.md (变更部分) 示例：
## 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 进行了天然的支持，开箱即用。
其他支持自定义命令的 IDE（如 Cline）可以通过配置自定义命令来实现，提示词可以直接借鉴 Cursor 的方案。
知易行难
重复需求未被检测到
场景：多人协作或者新人加入时，他想开发一个功能，其实已经在归档里已经有了，但是他输入后仍然触发了新的需求。
通过 /openspec-proposal 进行已归档需求测试时，它并没有想象的那么美好。我尝试了两个 AI IDE 都帮我重新生成了一份文档，问题出在哪里？LLM Prompt 工程与 IDE 实际执行能力之间的鸿沟。
我们来看提示词里的 Steps，第一步它描述了 review openspec 下的内容，但是它是通过 run xxx 这依赖于 Agent 的终端执行能力。如果因为一些原因失败了，它又会给你生成一份新的了。
- 它觉得它执行了，但实际没执行（非 Agent 模式）
- 它执行了，但是失败了
解法：
问题的核心是因为 OpenSpec 本身是一个 CLI 命令工具，Cursor 似乎也对自己的命令执行很有自信，但真实的环境总是复杂的。那我们就把命令执行的方案改为依赖 IDE 目前的 Codebase，让它强制总是先去读目录下的文件（我们已经在最终完整版的命令里添加相关逻辑）。
草案生成后如何修改
直接修改对应的文件即可。
我们可以看到无论是 Cursor 天然支持的命令还是他自己的 CLI 好像都没有提供 update 这个场景。
官方针对这个没有任何说明，AI 给了我一个回答，感觉也合理。
这是一个非常深刻的产品设计问题。
你没看错，**OpenSpec 的设计哲学里确实故意“遗漏”了 `update` 这个动作。**
这并不是开发者忘了做，而是基于 **“文档即真理（Docs as Code）”** 和 **“不可变历史”** 这两个核心设计理念。
### 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。
它提供的核心能力其实是文档管理功能，而文档本身就是可编辑的。考虑极端一些的场景，它其实只是给我们对已有功能进行归档。如果抛开 AI，它的逻辑也是成立的，只是它的存在正好可以让大模型从搜索代码到先搜索总结后的功能。
手动进行修改是它的哲学设计，但基于此也会延伸出来一个问题：没有特殊的 Prompt 约束，模型并不知道一个 change 下的文件是需要联动更新的，但是实际上它们是依赖关系。
我们还是需要自定义一个 /openspec-update 命令，来处理需求变更的场景，让 Prompt 只专注在修改 changes 下的文件内容。当用户调用它时，它会查询当前还未归档的变更，如果存在多个需要跟用户手动确认是作用于哪一个变更。
当我们运行归档时，他怎么知道要归档到哪里
我们回看标准目录，其实答案已经藏在那里。它是通过 changes/[change-name]/specs/[capability] 的 capability 来决定的。如果你发现有问题，因为这个不涉及到文件的联动更新，直接手动修改即可。
归档错误
我在执行一次之前归档需求的优化时碰到了报错。
MODIFIED failed for header “### Requirement: xx” - not found Aborted. No files were changed.
我们看到这个报错写的是变更的时候需求未找到。当处于变更状态下，变更的 specs 文件里会标明原有的需求是什么，我们当前这次 specs 里的需求跟原来归档的需求不一致，所以发生了这个问题。
临时解法：
这时候我们需要做以下几步检查：
- 你当前的变更仍然在
openspec/changes 目录下还是已经被移动了 openspec/changes/archive 下，如果是后者，你需要先把文件移动回来；
- 然后确认你的 spec 的需求已经和归档的保持一致；
- 重新运行
openspec/archive 命令；
长期解法：
针对命令执行报错的场景，我们需要在提示词中都显式声明，告诉它应该立即停止，然后抛出对应的信息，让用户进行手动验证。
不同的编辑器显示可能不同，功能符合我们的预期即可。
变更需求后归档的 spec 被覆盖
场景：当我存在一个已经归档的需求，然后我发现了一个 Bug，这时候我告诉它需求变更，它的 specs 文件里标明的是 MODIFIED 的，当我完成归档后，发现初始归档的内容被覆盖了。
核心问题：在 spec 的世界里只有三种动作：
而 MODIFIED 对 OpenSpec 来说意味的就是需求变更，是文件覆盖操作，这与我们的开发心智是存在一些区别的，它提倡的是增量式更新。
解法：
在任意变更前都先明确你的变更预期，检查 changes 下的 spec 文件的动作。
#### 1. ADDED (追加/新增)
* **定义**：向 Spec 文件中**插入**新的 `Requirement` 或 `Scenario`。
* **心智模型**：`Array.push(newScenario)` 或 `File.append(text)`。
* **典型场景**：
* 新功能上线。
* **优化需求（扩展型）**：比如“登录增加验证码”、“列表增加筛选功能”。虽然你在“优化”列表，但你在文档里是**加了一段描述**，并没有删改原来的列表查询逻辑。
* **边缘情况补全**：比如“增加网络超时的处理逻辑”。
#### 2. MODIFIED (覆盖/修改)
* **定义**：**替换** Spec 文件中已存在的某个 `Scenario` 的全部内容。
* **心智模型**：`Map.set(existingKey, newValue)` 或 `Overwrite`。
* **危险性**：⚠️ 高。因为它会丢弃旧的逻辑。
* **典型场景**：
* **业务规则变更**：比如“积分获取规则从 10元1分 变成 20元1分”。
* **Bug 修复（逻辑错误的）**：原来的 Spec 写错了（比如写成“允许空密码”），现在要修正这个错误。
* **重构（导致行为变化的）**：比如“同步处理改为异步处理，用户不再立即收到结果”。
#### 3. REMOVED (删除)
* **定义**：从 Spec 文件中**移除**某个 `Scenario`。
* **心智模型**：`Array.filter(item => item.id !== id)`。
* **典型场景**：
* 功能下线。
* 简化产品，砍掉不常用的功能。
顺便一提
大家可以看到一个趋势，目前社区的趋势已经从模型自身的军备竞赛回归到了我们熟悉的工程化。在 工程化落地阶段 有很多可以做的事情。CC 和 Cursor 都是调用 Claude，为什么 CC 有时感觉比 Cursor 强？因为它要求你先规划，再执行。现在大家跟进的 Plan 模式也是一样。
Plan 模式和 Spec 在单一对话上很像，它也提供了保存到本地的能力。大家在做的事其实是一样的，都是为了让模型有一个更稳定的输出，帮助我们解决实际的问题。
社区也有很多其他的 Spec 方案，颗粒度不一样。例如 GitHub Spec Kit，它的理念和哲学会有一些差别。
**OpenSpec** 和 **GitHub Spec Kit** 都是“规格驱动开发（SDD）”的工具，它们的目标一致（先写文档再写代码），但**设计哲学**和**适用场景**截然不同。
用一个最形象的比喻来概括：
* **GitHub Spec Kit** 像是 **“建造摩天大楼的总工程师”**。严谨、繁琐、流程长，适合从 0 到 1 搞大工程，强调“企业级治理”。
* **OpenSpec** 像是 **“敏捷开发的装修队长”**。轻快、直接、灵活，适合日常修修补补和快速迭代，强调“开发者体验”。
### 1. 核心差异对比表
| 特性 | **OpenSpec** (Fission-AI) | **Spec Kit** (GitHub) |
| :--- | :--- | :--- |
| **核心哲学** | **Agile Renovator(敏捷装修)**<br>轻量级，假设你是在一个**现有的**代码库上工作。 | **Structured Architect(结构化建筑师)**<br>重量级，假设你是从 0 开始构建一个全新的系统。 |
| **工作流** | **3 步循环** (Draft -> Review -> Apply)<br>只有三个命令，像 Git 一样简单。 | **4 阶段门控** (Specify -> Plan -> Tasks -> Implement)<br>每一步都有严格的“关卡”，必须通过才能进下一步。 |
| **适用场景** | **维护/迭代现有项目 (Brownfield)**<br>修 Bug、加功能、改逻辑。 | **全新项目启动 (Greenfield)**<br>做 Demo、新开一个微服务。 |
...
**OpenSpec 是 Spec Kit 的“实用主义”进化版。**
Spec Kit 像是教科书上的“瀑布流+敏捷”混合体，很理想化；而 OpenSpec 则是那个真正坐在你旁边写代码的同事，懂你需要什么，也懂你不想麻烦。
流程 & 完整提示词
这只是更适合我自己心智的提示词，可能一些错误场景也还没有碰到，你可以基于我的继续去演进或者直接使用。它的优势在于没有任何魔法，完全可以自己控制。
/openspec-proposal
## 描述
Scaffold a new OpenSpec change and validate strictly.
## 命令
<!-- OPENSPEC:START -->
**Guardrails**
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
- Keep changes tightly scoped to the requested outcome.
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
**Steps**
1. **CRITICAL PRE-CHECK**:
- **DO NOT assume context.** You MUST perform a **codebase search** (using your internal search tool) specifically targeting the `openspec/specs/` directory for keywords related to the user's request.
- **STOP AND ASK**: If you find _any_ existing spec files that seem related (even remotely), **STOP IMMEDIATELY**. Do not generate any scaffold. List the found specs and ask the user: "Did you mean to modify [filename] instead?"
- **Only proceed to Step 2** if the search returns ZERO relevant results.
2. **(Only if no duplicates found)** Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
**Reference**
- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
<!-- OPENSPEC:END -->
/openspec-update (自定义)
## 描述
Modify an existing, active OpenSpec draft(proposal, spec, tasks) without creating a new one.
## 命令
<!-- OPENSPEC:START -->
**Guardrails**
- **SCOPE RESTRICTION**: This command operates ONLY on files within `openspec/changes/`. Do NOT create new change folders. Do NOT edit `src/` code.
- **CONSISTENCY**: If requirements(`spec.md`)ordesign(`design.md`) change, you MUST update `tasks.md` to reflect these changes immediately.
- **INTERACTION**: If multiple active changes exist, you MUST ask the user to select one before editing any files.
**Steps**
1. **Discovery & Selection(Context Loading)**
- Run `openspec list` (orlist directories in `openspec/changes/`) to identify active drafts.
- **Scenario A(0 Active Changes)**:
- STOP and inform the user: "No active drafts found to update. Use `/openspec-proposal` to start a new one."
- **Scenario B(1 Active Change)**:
- Automatically select thisID(e.g., `feature-login`).
- Inform the user: "Updating active draft: `feature-login`..."
- **Read Files**: Read `proposal.md`, `tasks.md`, `design.md`, and `spec.md` inside that directory.
- **Scenario C(>1 Active Changes)**:
- List all found IDs.
- STOP and ask: "Multiple active drafts found. Which one do you want to update? (e.g., `feature-A` or `feature-B`)"
- Wait for user confirmation, then read the files of the selected ID.
2. **Intent Analysis & Execution**
- Analyze the user's update request(e.g., "Extract Modal component", "Change DB to Mongo").
- **Step 2.1: Update Truth(Spec/Design/Proposal)**:
- Modify `spec.md` if business requirements change.
- Modify `design.md` if technical implementation details change.
- Modify `proposal.md` if the high-level goal changes.
- **Step 2.2: Re-align Plan(Tasks)**:
- **CRITICAL**: Rewrite or adjust `tasks.md` to ensure it matches the new files from Step 2.1.
- If tasks were partially completed(`[x]`), try to preserve status where possible, but uncheck items if the logic underneath them has fundamentally changed.
3. **Validation**
- Run `openspec validate <id>` to ensure the update didn't break the document structure.
- Present the summary of changes to the user(e.g., "Updated `design.md` to include SharedModal; Added 2 new steps to `tasks.md`").
**Reference**
- Use `openspec list` to find targets.
- Always keep `tasks.md` as the executable plan for the current `spec.md`.
<!-- OPENSPEC:END -->
/openspec-apply
## 描述
Implement an approved OpenSpec change and keep tasks in sync.
## 命令
<!-- OPENSPEC:START -->
**Guardrails**
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
- Keep changes tightly scoped to the requested outcome.
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
**Steps** Track these steps as TODOs and complete them one by one.
1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria,Strictly follow the tasks.md sequence. Do not skip steps or merge tasks unless explicitly necessary.
2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
4. **Update `tasks.md` selectively:**
- Mark **implementation tasks** (e.g., "Create component", "Add API endpoint") as `- [x]` immediately after writing the code.
- **Do NOT** mark **verification/validation tasks** (e.g., "Verify login works", "Check responsiveness", "Run tests") as completed. Leave them as `- [ ]` for the user to confirm manually.
5. Reference `openspec list` or `openspec show <item>` when additional context is required.
**Reference**
- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
**tips**
If the user only enters this command, the latest `tasks.md` and files under the `specs/*` directory need to be read.
<!-- OPENSPEC:END -->
/openspec-archive
## 描述
Archive a deployed OpenSpec change and update specs.
## 命令
**Guardrails**
- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
- Keep changes tightly scoped to the requested outcome.
- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
**Steps**
1. Determine the change ID to archive:
- If this prompt already includes a specific change ID(for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
- If the conversation references a change loosely(for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
- Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
- If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
2. **PRE-CHECK**: Validate the change ID and status:
- Run `openspec list` to confirm the ID exists and is not already archived.
- **CRITICAL**: Run `openspec validate <id> --strict`.
- **STOP IF FAILED**: If validation reports ANY errors(e.g., unfinished tasks, malformed frontmatter), **DO NOT PROCEED**. Show the validation errors to the user and ask them to fix the issues first.
3. **ARCHIVE**: Only if validation passes, run `openspec archive <id> --yes`.
- This moves the change to `changes/archive/` and applies spec updates without prompts.
- (Optional) Use `--skip-specs` only if the user explicitly requested a tooling-only archive.
4. Review the command output to confirm the target specs were updated successfully.
**Reference**
- Use `openspec list` to confirm change IDs before archiving.
- Inspect refreshed specs with `openspec list --specs` after archiving to confirm the merge.
<!-- OPENSPEC:END -->
参考
1、https://openspec.dev/
2、https://github.com/Fission-AI/OpenSpec
3、https://github.com/github/spec-kit
4、https://aistudio.google.com
希望这篇关于 SDD 与 OpenSpec 在 AI 时代下的实践指南能对你有所帮助。如果你想了解更多关于 人工智能如何改变开发流程 或与其他开发者交流心得，欢迎访问 云栈社区。
发表于 4 天前
|
查看: 13|
回复: 0
