本文介绍了 Spec-Driven Development (SDD) 以及 OpenSpec 工具的使用，对比了两种 SDD 方案，并分享了在落地 SDD 过程中可能遇到的问题及解决方案。
原文标题：SDD 如何在复杂业务系统中真正落地？
原文作者：阿里云开发者
冷月清谈：
怜星夜思：
2、OpenSpec 和 GitHub Spec Kit 适用于不同的场景，你认为在什么情况下，选择轻量级的 OpenSpec 会比重量级的 GitHub Spec Kit 更有优势？反之呢？
3、文章提到了 AI 在 SDD 中的作用，你认为未来 AI 还能在 SDD 的哪些环节发挥更大的作用？
原文内容
发展历史
全称：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- 1.1 设计并实现移动端 Snackbar 组件
- 1.1.1 创建 MobileSnackbar 组件 (或复用现有组件库的类似组件)
- 1.1.2 实现底部弹出动画和样式
- 1.1.3 支持自定义内容和操作按钮
- 1.2 修改通知触发逻辑
- 1.2.1 在xxx.tsx中修改showPPTOutlineNotification
- 1.2.2 移除if (isMobileDevice()) return;判断
- 1.2.3 根据设备类型分发不同的通知展示方式 (PC 使用notification.info, Mobile 使用新 Snackbar)
- 1.3 验证与测试
- 1.3.1 验证移动端触发时机是否正确
- 1.3.2 验证移动端样式是否符合设计 (底部 Snackbar)
- 1.3.3 验证"去查看"按钮在移动端是否正常工作
## MODIFIED RequirementsRequirement: 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: xx" - not found Aborted. No files were changed.
我们看到这个报错写的是变更的时候需求未找到。当处于变更状态下，变更的 specs 文件里会标明原有的需求是什么，我们当前这次 specs 里的需求跟原来归档的需求不一致，所以发生了这个问题。
临时解法：
这时候我们需要做以下几步检查
-
你当前的变更仍然在
openspec/changes目录下还是已经被移动了openspec/changes/archive下，如果是后者，你需要先把文件移动回来； -
然后确认你的 spec 的需求已经和归档的保持一致；
-
重新运行
openspec/archive命令；
长期解法：
针对命令执行报错的场景，我们需要在提示词中都显式声明，告诉他应该立即停止，然后抛出对应的信息，让用户进行手动验证。（我们已经在最终完整版的命令里添加，这里不再赘述相关代码）
不同的编辑器显示可能不同，功能符合我们的预期即可。
变更需求后归档的 spec 被覆盖
场景：当我存在一个已经归档的需求，然后我发现了一个 bug，这时候我告诉他需求变更，他的 specs 文件里标明的是 MODIFIED 的，当我完成归档后，发现初始归档的内容被覆盖了。
核心问题：在 spec 的世界里只有三种动作
-
ADDED
-
MODIFIED
-
REMOVED
而 MODIFIED 对他来说意味的就是需求变更，是文件覆盖操作，与我们的开发心智是存在一些区别的，他提倡的是增量式更新。
解法：
在任意变更前都先明确你的变更预期，检查 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 方案，颗粒度不一样，这是另一个比较高星的仓库，他的理念和哲学会有一些差别。
**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、新开一个微服务。 文件管理 双文件夹模式<br> specs/(真理) 和changes/(变更) 分离。<br>不仅管“新建”，更擅长管“修改”。单向流动<br>通过 constitution.md(宪法) 定义原则。<br>通常会为你自动创建 Git 分支。Token 消耗 低。文档精简（约 200 行），只关注变更部分。 高。生成的文档非常详尽（约 800 行），包含大量样板信息。 上手难度 低 (npm install 即可)
2. 深度解析：为什么说 OpenSpec 更适合日常？
A. “修改” vs “新建” 的逻辑差异
* Spec Kit 的思维模型是线性向前的。当你用它做一个新功能时，它非常爽，会生成完美的需求文档、技术方案。但如果你只是想“把登录按钮往左移 10px”，Spec Kit 的那套“需求->计划->任务->实施”的重型流程会让你觉得像在杀鸡用牛刀。
* OpenSpec 专门解决了这个问题。它把变更（Change）作为一个独立的概念。
* 你可以发起一个“修改按钮位置”的 Change。
* 你可以发起一个“重构数据库”的 Change。
* 不论大小，流程都是统一的 Draft -> Apply -> Archive。B. 此时此刻的“真理” (Source of Truth)
* Spec Kit 倾向于把生成的 Spec 作为一个阶段性的产物。
* OpenSpec 引入了openspec/specs/目录作为永久的“真理来源”。
* 当你把一个功能 Archive（归档）后，它的 Spec 会被合并到主目录。
* 杀手级特性：下次你让 AI 改代码时，OpenSpec 会先让 AI 读specs/目录，AI 立刻就能知道“哦，这个功能上次是这样设计的”，防止了新代码破坏旧逻辑（Regression）。C. “宪法” vs “项目说明书”
* Spec Kit 有一个
constitution.md（宪法）的概念，里面写满了不可违背的原则（比如“必须使用 TDD”、“必须写注释”）。这很有企业级风范。
* OpenSpec 使用project.md，更像是一个“项目备忘录”。它更务实，通常只包含技术栈、目录结构和关键约定。
3. 如何选择？
选 OpenSpec，如果：
1. 你在维护一个现有的项目：你需要在巨大的代码山上修修补补，而不是每天都在
npm init新项目。
2. 你追求速度：你不想为了写一个简单的 API 接口而经历漫长的 4 步审批流程。
3. 你是个人开发者或小团队：你们需要规范，但不需要官僚主义。
4. 你在乎 Token 费用：OpenSpec 的 Prompt 更精简。
1. 你是 Tech Lead，要开一个新坑：你想在写第一行代码前，逼迫团队把所有细节（API 定义、数据库模型、甚至错误码）都想清楚。
2. 团队很大，水平参差不齐：你需要用constitution.md来强制所有人遵守编码规范，不给 AI（或人）自由发挥的空间。
3. 你需要产出非常详尽的文档：Spec Kit 生成的文档可以直接拿去给老板或客户汇报用。总结
OpenSpec 是 Spec Kit 的“实用主义”进化版。
Spec Kit 像是教科书上的“瀑布流+敏捷”混合体，很理想化；而 OpenSpec 则是那个真正坐在你旁边写代码的同事，懂你需要什么，也懂你不想麻烦。
流程 & 完整提示词
这只是更适合我自己心智的提示词，可能一些错误场景也还没有碰到，你可以基于我的继续去演进或者直接使用。他的优势在于没有任何魔法，完全可以自己控制。
## 描述 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 toopenspec/AGENTS.md(located inside theopenspec/directory—runls openspecoropenspec updateif 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
- CRITICAL PRE-CHECK:
- DO NOT assume context. You MUST perform a codebase search (using your internal search tool) specifically targeting theopenspec/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 2if the search returns ZERO relevant results.
2. (Only if no duplicates found) Choose a unique verb-ledchange-idand scaffoldproposal.md,tasks.md, anddesign.md(when needed) underopenspec/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 indesign.mdwhen the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
5. Draft spec deltas inchanges/<id>/specs/<capability>/spec.md(one folder per capability) using## ADDED|MODIFIED|REMOVED Requirementswith at least one#### Scenario:per requirement and cross-reference related capabilities when relevant.
6. Drafttasks.mdas 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 withopenspec validate <id> --strictand resolve every issue before sharing the proposal.Reference
- Use
openspec show <id> --json --deltas-onlyoropenspec show <spec> --type specto inspect details when validation fails.
- Search existing requirements withrg -n "Requirement:|Scenario:" openspec/specsbefore writing new ones.
- Explore the codebase withrg <keyword>,ls, or direct file reads so proposals align with current implementation realities.
<!-- OPENSPEC:END –>
## 描述 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 editsrc/code.
- CONSISTENCY: If requirements(spec.md)ordesign(design.md) change, you MUST updatetasks.mdto 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)
- Runopenspec list(orlist directories inopenspec/changes/) to identify active drafts.
- Scenario A(0 Active Changes):
- STOP and inform the user: “No active drafts found to update. Use/openspec-proposalto 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: Readproposal.md,tasks.md,design.md, andspec.mdinside 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-Aorfeature-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):
- Modifyspec.mdif business requirements change.
- Modifydesign.mdif technical implementation details change.
- Modifyproposal.mdif the high-level goal changes.
- Step 2.2: Re-align Plan(Tasks):
- CRITICAL: Rewrite or adjusttasks.mdto 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
- Runopenspec validate <id>to ensure the update didn’t break the document structure.
- Present the summary of changes to the user(e.g., “Updateddesign.mdto include SharedModal; Added 2 new steps totasks.md”).Reference
- Use
openspec listto find targets.
- Always keeptasks.mdas the executable plan for the currentspec.md.
<!-- OPENSPEC:END –>
## 描述 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 toopenspec/AGENTS.md(located inside theopenspec/directory—runls openspecoropenspec updateif 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), andtasks.mdto 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 intasks.mdis finished.
4. Updatetasks.mdselectively:
- 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. Referenceopenspec listoropenspec show <item>when additional context is required.Reference
- Use
openspec show <id> --json --deltas-onlyif you need additional context from the proposal while implementing.tips
If the user only enters this command, the latesttasks.mdand files under thespecs/*directory need to be read.<!-- OPENSPEC:END –>
## 描述 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 toopenspec/AGENTS.md(located inside theopenspec/directory—runls openspecoropenspec updateif 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), runopenspec listto surface likely IDs, share the relevant candidates, and confirm which one the user intends.
- Otherwise, review the conversation, runopenspec 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:
- Runopenspec listto confirm the ID exists and is not already archived.
- CRITICAL: Runopenspec 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 tochanges/archive/and applies spec updates without prompts.
- (Optional) Use--skip-specsonly 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 listto confirm change IDs before archiving.
- Inspect refreshed specs withopenspec list --specsafter 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