示例与实战配方
从真实变更的完整流程开始。每个配方都会展示你需要输入的命令以及对应的返回结果，你可以根据自己的场景匹配对应模式并直接复用。本文默认使用核心命令（propose、explore、apply、update、sync、archive）；如果扩展命令集能提供帮助，会特别注明。
开始前提醒：/opsx:propose 这类斜杠命令需要在AI 助手的聊天窗口中输入，openspec 命令则需要在终端中执行。如果你还不清楚这个区别，请先阅读命令工作原理。下文的对话记录中，You: 和 AI: 代表聊天内容，以 $ 开头的行代表终端命令。
还不确定要构建什么？ 如果你先用
/opsx:explore梳理清楚思路，大部分配方的效果会更好。配方 3 展示了实际用法，先探索再动手 指南会详细说明这样做的理由。
配方 1：小型功能，快速路径
适用场景： 你明确知道自己要做什么，且工作范围可控。这是最常用的配方。
整个过程仅需三条命令：提案（propose）、实现（apply）、归档（archive）。
You: /opsx:propose add-logout-button
AI: 已创建 openspec/changes/add-logout-button/
✓ proposal.md —— 变更原因与内容
✓ specs/ —— 新需求及其场景
✓ design.md —— 技术方案
✓ tasks.md —— 实现清单
已就绪，可开始实现。请运行 /opsx:apply。现在阅读方案。打开提案和增量规格说明。这正是 OpenSpec 的核心价值：在错误假设还只是一段话、而不是 400 行代码的时候就将其捕获。如果发现任何内容有问题，直接编辑对应产物，然后继续即可。
You: /opsx:apply
AI: 正在执行任务...
✓ 1.1 在页头添加登出按钮
✓ 1.2 点击时清除会话
✓ 1.3 添加确认弹窗
所有任务已完成！
You: /opsx:archive
AI: 正在归档 add-logout-button...
✓ 已将规格说明合并至 openspec/specs/auth/spec.md
✓ 已移动至 openspec/changes/archive/2026-06-22-add-logout-button/
完成。可开始下一个变更。完成。登出行为现在已经纳入你的规格说明体系，本次变更也连同完整上下文一起归档保存。
配方 2：缺陷修复
适用场景： 系统出现故障，你希望将修复过程记录为对行为的明确变更，而非一笔意义不明的提交。
缺陷修复的流程和功能开发完全一致，区别在于提案的表述方式：你需要描述正确的行为，而不是只写“修复缺陷”。
You: /opsx:propose fix-login-redirect-loop
AI: 已创建 openspec/changes/fix-login-redirect-loop/
提案记录了当前的异常行为和预期正确行为。
增量规格说明**修改**了重定向需求，使其现在精确且可测试。
已就绪，可开始实现。由于本次修复会以 MODIFIED（已修改）类型的需求和全新场景落地，后续人员（或下一次 AI 会话）不仅能看到你做了修复，还能明确“正确行为”的定义。之后按常规执行 /opsx:apply 和 /opsx:archive 即可。
提示：对于缺陷修复，好的场景描述就是纯文本形式的回归测试用例。例如：“GIVEN 用户已登出，WHEN 提交有效凭证，THEN 跳转至仪表盘且不会再次重定向。” 写下这样的场景，实现过程就有了明确的目标。
配方 3：先探索再提交
适用场景： 你遇到了问题但还没有明确的方案，不确定要构建什么，或者不知道哪种方案更合适。
先从 /opsx:explore 开始。它是不设固定结构、也不会生成任何产物的思考伙伴，会读取你的代码库并帮你做决策。
You: /opsx:explore
AI: 你想探索什么问题？
You: 页面加载很慢，但我不清楚时间花在了哪里。
AI: 让我看看……我发现了三个可能的原因：
1. 商品列表中的大图未做优化
2. 同步数据获取阻塞了渲染
3. 上下文变更触发了不必要的重渲染
我们先处理哪一个？
You: 数据获取的问题。
You: /opsx:propose optimize-product-list-fetching
AI: 已创建变更，提案基于我们刚才的发现生成。
已就绪，可开始实现。探索能让你在投入变更之前先理清思路。当思路清晰后，发起提案，AI 会继承之前的上下文继续推进。
配方 4：同时处理多个变更
适用场景： 你正在开发某个功能，突然有紧急缺陷需要优先处理。
变更都是独立文件夹，因此并行工作不会产生冲突。先处理紧急缺陷，发布后再回到原功能继续开发即可。
You: 我正在开发 add-dark-mode（深色模式）功能，但现在需要修复一个登录缺陷。
You: /opsx:propose fix-login-redirect
AI: 已创建 openspec/changes/fix-login-redirect/。已就绪，可开始实现。
You: /opsx:apply
AI: 缺陷修复已完成。所有任务均已完成。
You: /opsx:archive
AI: ✓ 已归档 fix-login-redirect。
You: 回到深色模式功能。
You: /opsx:apply add-dark-mode
AI: 正在恢复 add-dark-mode 变更。从任务 2.3 继续：更新页头……当有多个活跃变更时，在 /opsx:apply 后跟上变更名（如 add-dark-mode），就可以让 AI 定位到指定的变更。由于任务完成状态会记录在 tasks.md 中，AI 能精准知道你上次停在了哪个步骤。
如果多个变更需要同时归档，扩展命令 /opsx:bulk-archive 可以批量归档所有变更，并通过核对实际实现内容解决规格说明冲突。详见工作流。
配方 5：无行为变更的代码重构
适用场景： 你正在调整代码结构，且对外可见的行为需要保持完全一致。
这是比较特殊的情况：纯重构不需要对规格说明做任何修改。行为契约不会发生变化，只有实现逻辑会变。因此相关工作只体现在设计方案和任务清单中，规格说明增量为空或不存在。
You: /opsx:propose refactor-payment-module
AI: 已创建变更。提案明确了目标（拆分支付模块，不改变行为），
设计方案记录了新的代码结构。
由于行为完全一致，无需修改规格说明。
已就绪，可开始实现。要显式声明空增量，需要在变更的 .openspec.yaml 文件中设置 skip_specs: true：
schema: spec-driven
skip_specs: true如果没有这个标记，openspec validate 会拒绝零增量的变更（这样就能避免遗漏规格说明阶段的问题）；加上标记后，校验会通过，openspec status 也会将规格说明阶段标记为“已显式跳过”而非“待处理”。如果重构最终确实改变了行为，只需从 .openspec.yaml 中删除 skip_specs 配置并编写增量规格说明即可——校验规则会将“标记+规格说明文件”识别为冲突，避免旧标记被静默遗留。
归档带标记的变更不需要额外参数（因为没有需要合并的增量）。另外，终端命令的 --skip-specs 参数可以显式跳过规格说明步骤：
$ openspec archive refactor-payment-module --skip-specs这个参数在工具集成、CI 流水线以及仅修改文档的变更中非常实用。核心原则是：规格说明描述的是行为，如果行为没有变化，规格说明也不应该修改。详见概念。
配方 6：分步控制（扩展命令）
适用场景： 变更复杂度高或风险较大，你希望在推进前逐一审核每个产物。
核心命令 /opsx:propose 会一次性生成所有产物。如果你希望分步推进，可以启用扩展命令：
$ openspec config profile # 选择扩展工作流
$ openspec update # 将配置应用到当前项目现在你可以分步搭建和构建变更了：
You: /opsx:new add-2fa
AI: 已创建 openspec/changes/add-2fa/。下一步可创建：提案。
You: /opsx:continue
AI: 已创建 proposal.md。当前可创建：规格说明、设计方案。
You: /opsx:continue
AI: 已创建 specs/auth/spec.md。当前可创建：设计方案。每个产物生成后都可以自由审核、编辑，满意后再继续。如果你希望一次性生成剩余所有规划产物，可以使用 /opsx:ff 命令快进跳过剩余步骤。归档前，/opsx:verify 会检查实现内容是否真的符合规格说明。详见工作流。
配方 7：亲手实践完整流程
适用场景： 你已经安装了 OpenSpec，希望在自己的真实代码库中亲身体验工作流，而不是用玩具示例学习。
先启用扩展命令（详见配方 6），然后：
You: /opsx:onboard
AI: 欢迎使用 OpenSpec！我会带你基于实际代码库走完一次完整的变更流程。
让我先扫描一下，找一个我们可以一起完成的小型、安全的改进项……/opsx:onboard 会自动找到一个真实的小型改进项，创建变更、实现并归档它，同时讲解每一步操作。整个过程耗时 15 到 30 分钟，最后你会得到一个可以保留或丢弃的真实变更，是最温和的学习方式。详见命令。
从终端检查工作状态
任何时候，你都可以在终端中检查当前状态：
$ openspec list # 查看活跃变更
$ openspec show add-dark-mode # 查看单个变更的详细信息
$ openspec validate add-dark-mode # 检查变更结构是否合规
$ openspec view # 打开交互式仪表盘这些是只读检查工具，提案和构建操作仍然需要通过聊天中的斜杠命令完成。完整说明请参阅CLI 参考。