【AI Coding】OpenSpec — 规格驱动开发 (SDD) 工作流指南
工作流
本指南涵盖 OpenSpec 的常见工作流模式及各自的使用场景。基础设置请参考 Getting Started，命令参考见 Commands。
哲学：动作，而非阶段
传统工作流把你限制在阶段中：先规划，再实现，然后完成。但实际工作并不能 neatly 塞进盒子里。
OPSX 采取了不同的方式：
传统（阶段锁定）：
规划 ──────────► 实现 ──────────► 完成
│ │
│ "不能回头" │
└─────────────────┘
OPSX（流动动作）：
proposal ──► specs ──► design ──► tasks ──► implement
核心原则：
- 动作，而非阶段 — 命令是你可以做的事，不是困住你的阶段
- 依赖是赋能者 — 它们展示可能性，而非下一步强制要求
自定义： OPSX 工作流由定义产物（artifact）序列的 schema 驱动。详见 Customization。
两种模式
默认快速路径（core 配置）
新安装默认使用 core 配置，提供：
/opsx:propose/opsx:explore/opsx:apply/opsx:archive
典型流程：
/opsx:propose ──► /opsx:apply ──► /opsx:archive
扩展/完整工作流（自定义选择）
如果需要显式的脚手架和构建命令（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive、/opsx:onboard），通过以下命令启用：
openspec config profile
openspec update
工作流模式（扩展模式）
快速功能
当你明确要构建什么，只需执行时：
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
示例对话：
你: /opsx:new add-logout-button
AI: 已创建 openspec/changes/add-logout-button/
准备创建: proposal
你: /opsx:ff
AI: 正在创建所有规划产物...
✓ proposal.md
✓ specs/
✓ design.md
✓ tasks.md
准备实现！
你: /opsx:apply
AI: 正在执行任务...
✓ 在头部添加了登出按钮
✓ 实现了会话清理
✓ 添加了确认对话框
所有任务完成！
你: /opsx:archive
AI: ✓ 已合并 specs
✓ 已归档变更
适用于： 中小型功能、Bug 修复、直接的变更。
探索式
当需求不明确或需要先调查时：
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply
示例对话：
你: /opsx:explore
AI: 你想探索什么？
你: 我想提升页面加载性能，但我不确定瓶颈在哪。
AI: 让我帮忙调查...
[分析打包大小，识别慢查询，审查组件渲染模式]
我发现了三个主要瓶颈：
1. 大量未优化的图片
2. ProductList 中的同步数据获取
3. 上下文变更导致的重渲染
你想先处理哪个？
你: 我们先解决数据获取问题。
你: /opsx:new optimize-product-list-fetching
AI: 已创建变更。准备创建: proposal
你: /opsx:continue
AI: 根据我们的探索创建 proposal...
[撰写 proposal，融入调查洞察]
准备创建: specs, design
你接下来想要哪个？
你: /opsx:continue
AI: 正在创建 specs...
适用于： 性能优化、调试、架构决策、需求不明确的场景。
并行变更
同时处理多个变更：
变更 A: /opsx:new ──► /opsx:ff ──► /opsx:apply（进行中）
│
上下文切换
│
变更 B: /opsx:new ──► /opsx:ff ──────► /opsx:apply
示例对话：
你: 我在做 add-dark-mode，但被拉去修一个 bug
你: /opsx:new fix-login-redirect
AI: 已创建 openspec/changes/fix-login-redirect/
你: /opsx:ff
AI: ✓ 已创建规划产物
你: /opsx:apply
AI: 正在处理 fix-login-redirect...
[实现修复]
所有任务完成！
你: /opsx:archive
AI: ✓ 已归档 fix-login-redirect
你: 我们回到 dark mode 吧
你: /opsx:apply add-dark-mode
AI: 恢复 add-dark-mode...
从任务 2.3 继续: 更新 Header...
适用于： 并行工作流、紧急中断、团队协作。
当有多个已完成的变更时，使用 /opsx:bulk-archive：
你: /opsx:bulk-archive
AI: 发现 3 个已完成的变更:
- add-dark-mode（所有任务完成）
- fix-login-redirect（所有任务完成）
- update-footer（所有任务完成）
检查 spec 冲突...
⚠ add-dark-mode 和 update-footer 都涉及 specs/ui/
检查代码库以解决...
两个变更都已实现。将按时间顺序应用。
确认归档全部 3 个变更？
你: 确认
AI: ✓ 已归档 add-dark-mode
✓ 已归档 fix-login-redirect
✓ 已归档 update-footer
specs 按顺序合并: add-dark-mode → update-footer
批量归档会检测多个变更是否涉及相同的 specs，并通过检查实际实现来解决冲突。
完成一个变更
推荐的完成流程：
/opsx:apply ──► /opsx:verify ──► /opsx:archive
│ │
验证实现 提示同步
（如需要）
Verify：检查你的工作
/opsx:verify 从三个维度验证实现与产物的一致性：
你: /opsx:verify
AI: 正在验证 add-auth...
完整性 (COMPLETENESS)
✓ tasks.md 中所有 12 个任务已勾选
✓ specs 中所有需求都有对应代码
⚠ 场景"空闲后会话超时"未测试
正确性 (CORRECTNESS)
✓ 实现符合 spec 意图
✓ 来自场景的边界情况已处理
✓ 错误状态匹配 spec 定义
一致性 (COHERENCE)
✓ 设计决策反映在代码结构中
✓ 命名规范与 design.md 一致
⚠ 设计提到"事件驱动"但实现使用了轮询
摘要
─────────────────────────────
严重问题: 0
警告: 2
可归档: 是（带警告）
建议:
1. 为会话超时场景添加测试
2. 考虑按设计重构为事件驱动，或更新 design.md
Verify 检查内容：
| 维度 | 验证内容 |
|---|---|
| 完整性 | 所有任务完成、所有需求已实现、场景覆盖 |
| 正确性 | 实现匹配 spec 意图、边界情况已处理 |
| 一致性 | 设计决策反映在代码中、模式一致 |
Verify 不会阻止归档，但会暴露你可能想先处理的问题。
Archive：最终确定变更
/opsx:archive 完成变更并将其移入归档：
你: /opsx:archive
AI: 正在归档 add-auth...
产物状态:
✓ proposal.md 存在
✓ specs/ 存在
✓ design.md 存在
✓ tasks.md 存在（12/12 任务完成）
Delta specs: 尚未同步到 main
→ 是否现在同步？
你: 是
AI: ✓ 已同步 specs 到 openspec/specs/auth/spec.md
✓ 已移至 openspec/changes/archive/2025-01-24-add-auth/
变更归档成功。
如果 specs 未同步，Archive 会提示。它不会因任务未完成而阻止，但会发出警告。
何时使用什么
/opsx:ff vs /opsx:continue
| 场景 | 使用 |
|---|---|
| 需求明确，准备构建 | /opsx:ff |
| 探索中，想逐步审查 | /opsx:continue |
| 想在 specs 之前迭代 proposal | /opsx:continue |
| 时间紧迫，需要快速推进 | /opsx:ff |
| 复杂变更，想要控制 | /opsx:continue |
经验法则： 如果你能 upfront 描述完整范围，用 /opsx:ff。如果你边做边摸索，用 /opsx:continue。
何时更新 vs 重新开始
一个常见问题：什么时候更新现有变更可以接受，什么时候应该重新开始？
更新现有变更的条件：
- 意图相同，只是执行 refined
- 范围缩小（先 MVP，其余后续）
- 学习驱动的修正（代码库与预期不同）
- 基于实现发现的设计微调
重新开始一个变更的条件：
- 意图根本性改变
- 范围膨胀到完全不同的工作
- 原始变更可以独立标记为"完成"
- 补丁会造成更多混乱而非澄清
┌─────────────────────────────────────┐
│ 这还是同一个工作吗？ │
└──────────────┬──────────────────────┘
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
意图相同？ >50% 重叠？ 原始变更能否
问题相同？ 范围相同？ 不含这些变更
│ │ 就标记"完成"？
│ │ │
┌──┴──┐ ┌──┴──┐ ┌───┴───┐
│ │ │ │ │ │
是 否 是 否 否 是
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
更新 新建 更新 新建 更新 新建
示例："添加深色模式"
- "还需要支持自定义主题"→ 新建变更（范围膨胀）
- "系统偏好检测比预期复杂"→ 更新（意图相同）
- "先发布切换功能，偏好设置后续再加"→ 更新然后归档，再新建变更
最佳实践
保持变更聚焦
每个变更一个逻辑工作单元。如果你在做"添加功能 X 同时重构 Y"，考虑拆成两个独立变更。
为什么重要：
- 更容易审查和理解
- 更清晰的归档历史
- 可以独立发布
- 需要时回滚更简单
对不明确的需求使用 /opsx:explore
在提交变更之前，先探索问题空间：
你: /opsx:explore
AI: 你想探索什么？
你: 我们的 API 应该如何处理速率限制？
AI: 让我调查你当前的设置和可选方案...
[研究代码库，考虑各种模式]
我看到三种可选方案：
1. 基于中间件（简单，按端点）
2. Redis 后端（可扩展，共享状态）
3. 每用户令牌桶（公平，复杂）
你当前的技术栈建议选 #1 或 #2。你的规模如何？
探索能在创建产物之前澄清思路。
归档前验证
使用 /opsx:verify 检查实现与产物是否匹配：
你: /opsx:verify
AI: 正在验证 add-dark-mode...
✓ tasks.md 中所有任务已勾选
✓ specs 中的需求都有对应代码
✓ 设计决策已反映在实现中
可以归档！
在关闭变更前捕获不匹配问题。
清晰命名变更
好的命名让 openspec list 有价值：
推荐: 避免:
add-dark-mode feature-1
fix-login-redirect update
optimize-product-query changes
implement-2fa wip
命令速查表
完整命令详情和选项见 Commands。
| 命令 | 用途 | 何时使用 |
|---|---|---|
/opsx:propose |
创建变更 + 规划产物 | 快速默认路径（core 配置） |
/opsx:explore |
思考想法 | 需求不明确，需要调查 |
/opsx:new |
启动变更脚手架 | 扩展模式，显式产物控制 |
/opsx:continue |
创建下一个产物 | 扩展模式，逐步创建产物 |
/opsx:ff |
创建所有规划产物 | 扩展模式，范围明确 |
/opsx:apply |
实现任务 | 准备写代码 |
/opsx:verify |
验证实 | 扩展模式，归档前 |
/opsx:sync |
合并 delta specs | 扩展模式，可选 |
/opsx:archive |
完成变更 | 所有工作完成 |
/opsx:bulk-archive |
归档多个变更 | 扩展模式，并行工作 |
【AI Coding】OpenSpec — 规格驱动开发 (SDD) 工作流指南
https://qiyec.site/archives/EzzHQ0Pi