工作流
本指南介绍 OpenSpec 的常见工作流模式，以及各模式的使用场景。基础设置相关内容请参阅入门指南，命令参考请参阅命令参考。
核心理念：行动而非阶段
传统工作流会强制你按阶段推进：先规划，再实施，最后完成。但实际工作并不能被整洁地塞进一个个固定的阶段框里。
OPSX 采用了不同的工作方式：
text
传统（阶段锁定）：
PLANNING ────────► IMPLEMENTING ────────► DONE
│ │
│ "无法回退" │
└────────────────────┘
OPSX（灵活行动）：
proposal ──► specs ──► design ──► tasks ──► implement核心原则：
- 行动，而非阶段 - 命令是你可以执行的操作，而非你被困住的阶段
- 依赖是赋能项 - 它们展示的是当前可执行的操作，而非必须推进的下一个步骤
自定义： OPSX 工作流由定义工件序列的架构驱动。创建自定义架构的详细说明请参阅自定义。
两种模式
默认快速路径（core 配置档案）
新安装默认使用 core 配置档案，提供以下功能：
/opsx:explore/opsx:propose/opsx:apply/opsx:sync/opsx:archive
典型流程：
text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
(可选)先探索（值得养成的习惯）
/opsx:explore 是默认配置档案的一部分，并非高级附加组件。只要你有问题但还没有明确的方案，就应该使用这个命令——在使用 AI 助手时，这种情况非常普遍。
text
你: /opsx:explore
AI: 你想探索什么内容？
你: 我们的搜索结果很陈旧，我不确定是缓存、索引还是查询本身的问题。
AI: 让我看看……[读取搜索服务和缓存层]
是索引的问题：它只在夜间重建，所以编辑内容要到第二天才会显示。有两个解决方案：写入时重建（实现简单，负载更高）或短TTL缓存失效（组件更多，负载更低）。考虑到你的写入量很低，写入时重建是更简洁的修复方案。需要明确范围吗？
你: 需要。
你: /opsx:propose rebuild-search-index-on-write探索不会生成任何产物，也不会编写任何代码。这是一次零成本、无风险的对话，能将模糊的担忧转化为明确的变更，因此后续生成的提案会更精准。如果你已经清楚自己想要什么，可以跳过这一步，直接使用 /opsx:propose。完整指南：先探索。
扩展/完整工作流（自定义选择）
如果你需要显式的脚手架构建命令（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard），可以通过以下命令启用：
bash
openspec config profile
openspec update工作流模式（扩展模式）
快速功能开发
当你明确要开发的功能，只需要执行操作时：
text
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive对话示例：
text
你: /opsx:new add-logout-button
AI: 已创建 openspec/changes/add-logout-button/ 目录
准备生成：提案
你: /opsx:ff
AI: 正在生成所有规划产物……
✓ proposal.md
✓ specs/ 目录
✓ design.md
✓ tasks.md
准备就绪，可以开始实现！
你: /opsx:apply
AI: 正在执行任务……
✓ 已在页头添加登出按钮
✓ 已实现会话清除逻辑
✓ 已添加确认弹窗
所有任务完成！
你: /opsx:archive
AI: ✓ 已合并规范文档
✓ 已归档变更适用场景： 中小型功能、缺陷修复、逻辑简单的变更。
探索式开发
当需求不明确，或需要先调研分析时：
text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply对话示例：
text
你: /opsx:explore
AI: 你想探索什么内容？
你: 我想优化页面加载性能，但不确定瓶颈在哪里。
AI: 让我帮你调研分析……
[分析打包体积、定位慢查询、审查组件渲染模式]
我发现了三个主要瓶颈：
1. 未优化的大体积图片
2. ProductList 组件的同步数据获取
3. 上下文变更导致的重复渲染
你想先解决哪个问题？
你: 先解决数据获取的问题吧。
你: /opsx:new optimize-product-list-fetching
AI: 已创建变更，准备生成提案
你: /opsx:continue
AI: 基于我们的探索结果生成提案……
[撰写提案，纳入调研分析结论]
准备就绪，接下来要生成规范和设计文档，你想先做哪个？
你: /opsx:continue
AI: 正在生成规范文档……适用场景： 性能优化、缺陷调试、架构决策、需求不明确的场景。
并行变更
同时处理多个变更：
text
变更A: /opsx:new ──► /opsx:ff ──► /opsx:apply（进行中）
│
任务切换
│
变更B: /opsx:new ──► /opsx:ff ──────► /opsx:apply对话示例：
text
你: 我正在开发暗黑模式功能，但被安排去修复一个缺陷。
你: /opsx:new fix-login-redirect
AI: 已创建 openspec/changes/fix-login-redirect/ 目录
你: /opsx:ff
AI: ✓ 已生成规划产物
你: /opsx:apply
AI: 正在处理登录重定向缺陷修复……
[实现修复逻辑]
所有任务完成！
你: /opsx:archive
AI: ✓ 已归档登录重定向修复变更
你: 继续处理暗黑模式功能吧。
你: /opsx:apply add-dark-mode
AI: 正在恢复暗黑模式功能的开发……
从任务 2.3 继续：更新页头组件……适用场景： 并行工作流、紧急任务插入、团队协作场景。
当你完成多个变更后，可以使用 /opsx:bulk-archive：
text
你: /opsx:bulk-archive
AI: 发现 3 个已完成的变更：
- add-dark-mode（所有任务完成）
- fix-login-redirect（所有任务完成）
- update-footer（所有任务完成）
正在检查规范文档冲突……
⚠ add-dark-mode 和 update-footer 都涉及 specs/ui/ 目录下的规范
正在检查代码库以解决冲突……
两个变更均已实现，将按时间顺序归档。
是否归档全部 3 个变更？
你: 是
AI: ✓ 已归档 add-dark-mode
✓ 已归档 fix-login-redirect
✓ 已归档 update-footer
规范文档已按以下顺序合并：add-dark-mode → update-footer批量归档功能会检测多个变更是否涉及同一份规范文档，并通过检查实际已实现的代码来解决冲突。
完成变更
推荐的完成流程：
text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
│ │
验证实现 需要时提示同步验证：检查你的工作
/opsx:verify 会从三个维度验证实现与产物的匹配度：
text
你: /opsx:verify
AI: 正在验证 add-auth 变更……
**完整性**
✓ tasks.md 中的 12 个任务均已完成
✓ 规范文档中的所有需求都有对应代码实现
⚠ “无操作超时会话”场景未编写测试
**正确性**
✓ 实现符合规范文档的预期目标
✓ 场景中的边界情况均已处理
✓ 错误状态与规范定义一致
**一致性**
✓ 设计决策已体现在代码结构中
✓ 命名规范与 design.md 保持一致
⚠ 设计文档提及“事件驱动”模式，但实现使用了轮询机制
**总结**
─────────────────────────────
严重问题：0
警告：2
是否可归档：是（存在警告）
建议：
1. 为无操作超时会话场景添加测试用例
2. 按照设计重构为事件驱动模式，或更新 design.md 文档验证功能会检查以下内容：
| 维度 | 检查内容 |
|---|---|
| 完整性 | 所有任务完成、所有需求已实现、场景已覆盖 |
| 正确性 | 实现符合规范预期、边界情况已处理 |
| 一致性 | 设计决策已体现在代码中、模式保持一致 |
验证不会阻止归档操作，但会列出你可能需要先处理的问题。
归档：完成变更
/opsx:archive 会完成变更并将其移入归档目录：
text
你: /opsx:archive
AI: 正在归档 add-auth 变更……
产物状态：
✓ proposal.md 存在
✓ specs/ 目录存在
✓ design.md 存在
✓ tasks.md 存在（12/12 任务完成）
增量规范文档：尚未同步到主分支
→ 是否现在同步？
你: 是
AI: ✓ 已将规范文档同步到 openspec/specs/auth/spec.md
✓ 已移入 openspec/changes/archive/2025-01-24-add-auth/ 目录
变更归档成功。如果规范文档未同步，归档操作会弹出提示。它不会因未完成任务而阻止归档，但会发出警告。
使用场景指南
/opsx:ff 与 /opsx:continue 的区别
| 场景 | 适用命令 |
|---|---|
| 需求明确，准备开始构建 | /opsx:ff |
| 处于探索阶段，希望逐步审查每个步骤 | /opsx:continue |
| 希望在生成规范前迭代提案 | /opsx:continue |
| 时间紧迫，需要快速推进 | /opsx:ff |
| 变更复杂，需要精细控制流程 | /opsx:continue |
经验法则： 如果你能提前描述完整的变更范围，使用 /opsx:ff；如果你是在推进过程中逐步明确需求，使用 /opsx:continue。
何时更新现有变更 vs 新建变更
常见问题：什么时候可以更新现有变更，什么时候需要新建一个变更？
以下情况适合更新现有变更：
- 核心目标不变，仅优化执行方案
- 范围缩小（先实现最小可行版本，其余部分后续补充）
- 基于调研的修正（代码库实际情况与预期不符）
- 基于实现发现的细节调整设计
以下情况适合新建变更：
- 核心目标发生根本变化
- 范围扩大到完全不同的工作内容
- 原有变更可以独立标记为“已完成”
- 补丁式修改反而会让变更逻辑更混乱
text
┌─────────────────────────────────────┐
│ 这是同一项工作吗？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
核心目标一致？ 重叠度超过50%？ 原有变更不包含这些
问题相同？ 范围一致？ 修改也能标记为“完成”？
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
是 否 是 否 否 是
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
更新 新建 更新 新建 更新 新建示例：“添加暗黑模式”功能
- “需要额外支持自定义主题” → 新建变更（范围扩大）
- “系统偏好检测比预期更复杂” → 更新现有变更（核心目标不变）
- “先上线切换开关，后续再添加偏好设置” → 先更新现有变更并归档，再新建变更
最佳实践
保持变更聚焦
每个变更只包含一个逻辑工作单元。如果你要同时做“添加X功能”和“重构Y模块”，建议拆分为两个独立的变更。
为什么这很重要：
- 更易于审查和理解
- 归档历史更清晰
- 可独立发布
- 需要回滚时更简单
需求不明确时使用 /opsx:explore
在确定变更前，先探索问题域：
text
你: /opsx:explore
AI: 你想探索什么内容？
你: 我们的 API 应该如何处理限流？
AI: 让我调研你当前的架构和可选方案……
[研究代码库、考虑现有模式]
我看到了三种可行的方案：
1. 基于中间件（实现简单，按端点配置）
2. 基于Redis（可扩展，支持共享状态）
3. 按用户配置令牌桶（公平性好，实现复杂）
你当前的技术栈更适合方案1或2，你们的业务规模有多大？探索能帮你理清思路，再创建相关产物。
归档前先验证
使用 /opsx:verify 检查实现与产物是否一致：
text
你: /opsx:verify
AI: 正在验证暗黑模式变更……
✓ tasks.md 中的所有任务均已完成
✓ 规范文档中的所有需求都有对应代码实现
✓ 设计决策已体现在实现中
可以归档了！在关闭变更前就能发现不一致的问题。
规范变更命名
清晰的命名能让 openspec list 命令更有用：
| 推荐 | 避免 |
|---|---|
| add-dark-mode | feature-1 |
| fix-login-redirect | update |
| optimize-product-query | changes |
| implement-2fa | wip |
命令快速参考
完整的命令详情和选项请参阅命令。
| 命令 | 用途 | 适用场景 |
|---|---|---|
/opsx:propose | 创建变更及规划产物 | 快速默认路径（core 配置文件） |
/opsx:explore | 与AI共同梳理思路 | 不确定时的首选：需求不明确、需要调研、对比方案时 |
/opsx:new | 启动变更脚手架 | 扩展模式，手动控制产物 |
/opsx:continue | 创建下一个产物 | 扩展模式，逐步创建产物 |
/opsx:ff | 创建全部规划产物 | 扩展模式，范围明确时 |
/opsx:apply | 执行任务 | 准备编写代码时 |
/opsx:verify | 验证实现 | 扩展模式，归档前 |
/opsx:sync | 合并增量规格说明 | 扩展模式，可选操作 |
/opsx:archive | 完成变更 | 所有工作完成后 |
/opsx:bulk-archive | 批量归档多个变更 | 扩展模式，并行工作时 |