OpenSpec 命令指南：让你的 AI 编程助手更听话
你可能已经用上了 Claude Code、Cursor 或者 Windsurf 这类 AI 编程助手，写代码效率确实高了不少。但你有没有遇到过这种情况：想做一个功能改动，AI 一口气给你生成一大堆代码，改完之后发现有些地方不对，想回溯都找不到当初的设计思路？
OpenSpec 就是来解决这个问题的。它提供了一套斜杠命令，让你能规范地管理代码变更的整个生命周期——从最初的灵感探索，到最终的归档收尾，每一步都有迹可循。
两套命令，按需选择
OpenSpec 把命令分成了两套。默认的叫 core 精简命令，够大多数人日常使用：
| 命令 | 干什么用 |
|---|---|
/opsx:propose |
一步到位创建变更并生成规划产物 |
/opsx:explore |
先探索想法，想清楚再动手 |
/opsx:apply |
按任务列表开始写代码 |
/opsx:sync |
把变更的规格合并到主规格 |
/opsx:archive |
变更完成，归档收尾 |
如果你想要更精细的控制，还有一套扩展命令可以启用：
| 命令 | 干什么用 |
|---|---|
/opsx:new |
只创建变更骨架，不生成产物 |
/opsx:continue |
按依赖关系一个个生成产物 |
/opsx:ff |
快进：一口气生成所有规划产物 |
/opsx:verify |
检查实现是否符合规划 |
/opsx:bulk-archive |
批量归档多个变更 |
/opsx:onboard |
交互式教程，带你走一遍完整流程 |
想启用扩展命令的话，运行 openspec config profile 选 workflows，然后在项目里执行 openspec update 就行。
从零开始：propose 和 explore
大多数时候，你只需要一个 /opsx:propose 就够了。告诉它你要做什么，它会帮你创建变更目录，生成 proposal、specs、design、tasks 这些规划产物，然后停下来等你确认。
/opsx:propose add-dark-mode
执行完之后，你的变更目录里就有了完整的规划文档。这时候跑 /opsx:apply 就能开始写代码了。
但如果你还没想清楚要怎么做呢？用 /opsx:explore。这个命令不会创建任何产物，它就是帮你和 AI 一起探讨问题。你可以问它当前代码库的架构，比较不同的实现方案，等想清楚了再切到 propose。
比如你不确定移动端该用 JWT 还是 OAuth，先 explore 一下，让 AI 分析现有代码，对比各种方案的优缺点。想明白了，一句 /opsx:propose add-jwt-auth 就能启动正式变更。
写代码阶段：apply 和 verify
规划产物都准备好之后，/opsx:apply 会读取 tasks.md，按照任务列表一项项实现。每完成一项就打个勾，中断了也没关系，下次继续会从断点处接着来。
如果你对 AI 的实现不放心，/opsx:verify 能帮你检查三个维度：
- 完整性：任务都做完了吗？需求都实现了吗？
- 正确性：实现和规格意图一致吗？边界情况处理了吗？
- 一致性：设计决策在代码里体现了吗？命名风格统一吗？
verify 不会阻止你归档，但它会把发现的问题按严重程度列出来，让你决定要不要修。
两种工作节奏：continue 和 ff
扩展命令里有两种生成产物的方式，适合不同的工作习惯。
/opsx:continue 是慢节奏：每次只生成一个产物，生成完你看看，满意了再继续。适合复杂变更，你想逐个把关每个规划文档。
/opsx:ff 是快节奏：一口气把 proposal、specs、design、tasks 全生成出来。适合你对要做的事情已经很清楚了，不需要一步步确认。
两种方式生成的产物是一样的，区别只在于你介入的频率。
收尾：sync 和 archive
代码写完了，该收尾了。/opsx:archive 会检查产物完整性，提醒你是否要同步规格，然后把变更移到归档目录。归档后的东西不会丢，都在 openspec/changes/archive/ 里留着，随时可以回溯。
/opsx:sync 一般不需要手动调用，archive 会自动提醒你。但如果你在做一个长期变更，想先把规格合并到主分支，可以提前 sync 一下。
如果你同时完成了好几个变更，/opsx:bulk-archive 能帮你一次性处理。它会自动检测规格冲突，按创建顺序归档。
新手上路：onboard
第一次用 OpenSpec 的话，/opsx:onboard 是个不错的选择。它会扫描你的代码库，找一个真实的改进点，然后带你完整走一遍 propose → specs → design → tasks → apply → verify → archive 的全流程。用的是你自己的代码，不是玩具例子，大概 15-30 分钟能走完。
不同工具的语法差异
同一个命令，在不同 AI 工具里的写法有点区别：
| 工具 | 语法示例 |
|---|---|
| Claude Code | /opsx:propose、/opsx:apply |
| Cursor | /opsx-propose、/opsx-apply |
| Windsurf | /opsx-propose、/opsx-apply |
| Copilot (IDE) | /opsx-propose、/opsx-apply |
Claude Code 用冒号分隔，其他大多用连字符。命令的功能是一样的，只是格式不同。
遇到问题怎么办
"Change not found"：AI 不知道你要操作哪个变更。要么明确指定名字（/opsx:apply add-dark-mode），要么检查一下变更目录是不是真的存在。
"No artifacts ready"：所有产物要么已完成，要么被依赖卡住了。跑 openspec status --change <name> 看看是什么在挡路。
命令没反应：确保 OpenSpec 已经初始化（openspec init），然后 openspec update 重新生成技能文件。
产物生成得不对：可以在 openspec/config.yaml 里加项目上下文，或者用 /opsx:continue 代替 /opsx:ff，这样每个产物你都能先看看再继续。
OpenSpec 的命令设计其实挺直觉的：explore 想清楚，propose 定下来，apply 写代码，verify 检查，archive 收工。把这几个串起来，你的 AI 编程助手就不会变成脱缰的野马了。