工作流
本指南涵盖 OpenSpec 的常见工作流模式及其适用场景。基础设置请参阅快速入门。命令参考请查阅命令。
核心理念：行动而非阶段
传统工作流强制你经历各个阶段：规划、实施、然后完成。但实际工作无法整齐地归入这些框架。
OPSX 采用了不同的方法：
text
传统（阶段锁定）：
规划 ────────► 实施 ────────► 完成
│ │
│ "无法回头" │
└────────────────────┘
OPSX（流动行动）：
提案 ──► 规格 ──► 设计 ──► 任务 ──► 实施核心原则：
- 行动而非阶段 - 命令是你能执行的操作，而非你被困住的阶段
- 依赖是使能器 - 它们展示的是可能性，而非下一步的必需要求
自定义： OPSX 工作流由定义工件序列的模式驱动。有关创建自定义模式的详细信息，请参阅自定义。
两种模式
默认快速路径 (core 配置)
新安装默认使用 core 配置，提供以下命令：
/opsx:propose/opsx:explore/opsx:apply/opsx:archive
典型流程：
text
/opsx:propose ──► /opsx:apply ──► /opsx:archive扩展/完整工作流（自定义选择）
如果您需要明确的脚手架和构建命令（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive、/opsx:onboard），请通过以下方式启用：
bash
openspec config profile
openspec update工作流模式（扩展模式）
快速功能
当您明确要构建什么，只需执行时：
text
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive示例对话：
text
You: /opsx:new add-logout-button
AI: 已创建 openspec/changes/add-logout-button/
准备创建：提案
You: /opsx:ff
AI: 正在创建所有规划产物...
✓ proposal.md
✓ specs/
✓ design.md
✓ tasks.md
准备就绪，可以开始实现！
You: /opsx:apply
AI: 正在处理任务...
✓ 已在页眉添加登出按钮
✓ 已实现会话清除
✓ 已添加确认对话框
所有任务完成！
You: /opsx:archive
AI: ✓ 已合并规范
✓ 已归档变更最适合： 中小型功能、错误修复、直接的变更。
探索性
当需求不明确或需要先调查时：
text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply示例对话：
text
You: /opsx:explore
AI: 您想探索什么？
You: 我想提升页面加载性能，但不确定瓶颈在哪里。
AI: 让我来帮您调查...
[分析包大小，识别慢查询，审查组件渲染模式]
我发现了三个主要瓶颈：
1. 大型未优化的图片
2. ProductList 中的同步数据获取
3. 上下文变化导致的重新渲染
您想先解决哪个？
You: 我们先处理数据获取问题。
You: /opsx:new optimize-product-list-fetching
AI: 已创建变更。准备创建：提案
You: /opsx:continue
AI: 正在基于我们的探索创建提案...
[编写包含调查见解的提案]
准备创建：规范、设计
您接下来想创建哪个？
You: /opsx:continue
AI: 正在创建规范...最适合： 性能优化、调试、架构决策、需求不明确的情况。
并行变更
同时处理多个变更：
text
变更 A: /opsx:new ──► /opsx:ff ──► /opsx:apply (进行中)
│
上下文切换
│
变更 B: /opsx:new ──► /opsx:ff ──────► /opsx:apply示例对话：
text
You: 我正在处理 add-dark-mode，但被拉去修复一个 bug
You: /opsx:new fix-login-redirect
AI: 已创建 openspec/changes/fix-login-redirect/
You: /opsx:ff
AI: ✓ 已创建规划产物
You: /opsx:apply
AI: 正在处理 fix-login-redirect...
[实现修复]
所有任务完成！
You: /opsx:archive
AI: ✓ 已归档 fix-login-redirect
You: 我们继续处理暗黑模式
You: /opsx:apply add-dark-mode
AI: 正在恢复 add-dark-mode...
从任务 2.3 开始：更新页眉...最适合： 并行工作流、紧急中断、团队协作。
当您有多个已完成的变更时，使用 /opsx:bulk-archive：
text
You: /opsx:bulk-archive
AI: 发现 3 个已完成的变更：
- add-dark-mode (所有任务已完成)
- fix-login-redirect (所有任务已完成)
- update-footer (所有任务已完成)
正在检查规范冲突...
⚠ add-dark-mode 和 update-footer 都涉及 specs/ui/
正在检查代码库以解决冲突...
两个变更都已实现。将按时间顺序应用。
是否归档所有 3 个变更？
You: 是
AI: ✓ 已归档 add-dark-mode
✓ 已归档 fix-login-redirect
✓ 已归档 update-footer
规范已按顺序合并：add-dark-mode → update-footer批量归档会检测多个变更是否涉及相同规范，并通过检查实际实现来解决冲突。
完成变更
推荐的完成流程：
text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
│ │
验证实现 提示同步（如果需要）验证：检查您的工作
/opsx:verify 从三个维度验证实现是否符合您的产物：
text
You: /opsx:verify
AI: 正在验证 add-auth...
完整性
✓ tasks.md 中的所有 12 个任务都已勾选
✓ 规范中的所有需求都有对应代码
⚠ 场景 "会话超时后不活动" 未测试
正确性
✓ 实现符合规范意图
✓ 场景中的边缘情况已处理
✓ 错误状态符合规范定义
一致性
✓ 设计决策体现在代码结构中
✓ 命名约定与 design.md 一致
⚠ 设计提到 "事件驱动" 但实现使用轮询
总结
─────────────────────────────
严重问题：0
警告：2
准备归档：是（有警告）
建议：
1. 为会话超时场景添加测试
2. 考虑按设计重构为事件驱动，或更新 design.md验证检查内容：
| 维度 | 验证内容 |
|---|---|
| 完整性 | 所有任务完成，所有需求已实现，场景已覆盖 |
| 正确性 | 实现符合规范意图，边缘情况已处理 |
| 一致性 | 设计决策体现在代码中，模式保持一致 |
验证不会阻止归档，但它会揭示您可能需要先处理的问题。
归档：完成变更
/opsx:archive 完成变更并将其移至归档：
text
You: /opsx:archive
AI: 正在归档 add-auth...
产物状态：
✓ proposal.md 存在
✓ specs/ 存在
✓ design.md 存在
✓ tasks.md 存在 (12/12 任务完成)
增量规范：尚未同步到主分支
→ 您想现在同步吗？
You: 是
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。
何时更新与何时重新开始
一个常见问题：何时可以更新现有变更，何时应该开始新变更？
在以下情况下更新现有变更：
- 意图相同，执行优化
- 范围缩小（先做 MVP，其余稍后）
- 基于学习的修正（代码库与预期不同）
- 基于实现发现的设计调整
在以下情况下开始新变更：
- 意图根本改变
- 范围爆炸到完全不同的工作
- 原始变更可以单独标记为“完成”
- 补丁会比澄清更令人困惑
text
┌─────────────────────────────────────┐
│ 这是同一项工作吗？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
意图相同？ >50% 重叠？ 原始变更能否
问题相同？ 范围相同？ 不包含这些变更
│ │ 就“完成”？
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
是 否 是 否 否 是
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
更新 新建 更新 新建 更新 新建示例：“添加暗黑模式”
- “还需要支持自定义主题” → 新变更（范围爆炸）
- “系统偏好检测比预期更难” → 更新（意图相同）
- “我们先发布开关，稍后添加偏好设置” → 更新然后归档，然后新建变更
最佳实践
保持变更聚焦
每个变更一个逻辑工作单元。如果您正在做“添加功能 X 并重构 Y”，请考虑两个单独的变更。
为什么重要：
- 更容易审查和理解
- 更清晰的归档历史
- 可以独立发布
- 如需要，回滚更简单
对不明确的需求使用 /opsx:explore
在承诺变更之前，先探索问题空间：
text
You: /opsx:explore
AI: 您想探索什么？
You: 我们应该如何处理 API 的速率限制？
AI: 让我调查您当前的设置和选项...
[研究代码库，考虑模式]
我看到我们可以采取三种方法：
1. 基于中间件（简单，按端点）
2. 基于 Redis（可扩展，共享状态）
3. 按用户的令牌桶（公平，复杂）
您当前的技术栈建议使用 #1 或 #2。您的规模如何？探索可以在创建产物之前理清思路。
归档前验证
使用 /opsx:verify 检查实现是否符合产物：
text
You: /opsx:verify
AI: 正在验证 add-dark-mode...
✓ tasks.md 中的所有任务都已勾选
✓ 规范中的需求都有对应代码
✓ 设计决策体现在实现中
准备归档！在关闭变更之前捕获不匹配项。
清晰命名变更
好的名称使 openspec list 更有用：
text
好的： 避免：
add-dark-mode feature-1
fix-login-redirect update
optimize-product-query changes
implement-2fa wip命令快速参考
完整的命令详情和选项，请参阅 命令。
| 命令 | 用途 | 使用场景 |
|---|---|---|
/opsx:propose | 创建变更及规划工件 | 快速默认路径（core 配置） |
/opsx:explore | 深入思考想法 | 需求不明确，需要调研时 |
/opsx:new | 启动变更脚手架 | 扩展模式，显式控制工件 |
/opsx:continue | 创建下一个工件 | 扩展模式，逐步创建工件 |
/opsx:ff | 创建所有规划工件 | 扩展模式，范围明确时 |
/opsx:apply | 实施任务 | 准备编写代码时 |
/opsx:verify | 验证实现 | 扩展模式，归档前 |
/opsx:sync | 合并增量规格 | 扩展模式，可选步骤 |
/opsx:archive | 完成变更 | 所有工作完成时 |
/opsx:bulk-archive | 归档多个变更 | 扩展模式，并行工作时 |