当下AI编码助手（Claude Code、Cursor等）的普及，让开发效率迎来了质的提升，但随之而来的是Vibe Coding带来的代码结构混乱、需求不明确、团队协作难等问题。而Fission-AI推出的OpenSpec框架，凭借一套标准化的slash命令体系，让AI编码从“随性开发”走向“规范流程化”，完美解决了上述痛点。
本文将基于OpenSpec官方文档，为大家全面解析其核心命令体系，从基础使用到进阶技巧，让你轻松掌握这套能大幅提升AI编码效率和规范性的工具命令。
先搞懂：OpenSpec命令的两大核心体系
OpenSpec的命令并非杂乱无章，而是根据使用场景分为默认快速工作流（core配置） 和扩展工作流 两大体系，前者满足日常快速开发需求，后者适配复杂开发场景的精细化控制，默认全局启用的是core配置，如需开启扩展工作流，执行以下两步即可：
- 运行
openspec config profile，选择workflows； - 在项目中执行
openspec update。
两大体系的命令各有侧重，先通过一张表快速了解核心命令的基础用途，后续再逐一详解：
默认快速工作流（core）
| 命令 | 核心用途 |
|---|---|
/opsx:propose | 一步创建变更并生成所有规划制品 |
/opsx:explore | 开发前梳理思路、调研方案、明确需求 |
/opsx:apply | 执行变更任务，编写代码实现功能 |
/opsx:archive | 归档已完成的变更，留存审计痕迹 |
扩展工作流
| 命令 | 核心用途 |
|---|---|
/opsx:new | 初始化新变更的基础脚手架 |
/opsx:continue | 按依赖关系逐步生成下一个制品 |
/opsx:ff | 快速生成所有规划制品（一步到位） |
/opsx:verify | 验证代码实现与制品要求是否一致 |
/opsx:sync | 将变更的增量规格合并到主规格中 |
/opsx:bulk-archive | 批量归档多个已完成变更，处理规格冲突 |
/opsx:onboard | 交互式教程，引导熟悉完整OpenSpec工作流 |
逐个吃透：OpenSpec核心命令详解
所有命令均适用于AI编码助手的聊天界面，且支持上下文推断（部分命令可省略变更名称），以下详解每个命令的语法、功能、示例和实用技巧，内容均来自官方文档，保证严谨性。
一、默认快速工作流命令（新手首选）
这套命令的核心是简洁高效，无需关注细节，一键完成核心操作，适合需求明确的简单开发场景。
1. /opsx:propose：快速启动变更的“万能入口”
语法：/opsx:propose [change-name-or-description]
参数为非必填，可传入短横线命名的变更名（如add-dark-mode）或自然语言描述。
核心功能：一步创建变更文件夹openspec/changes/<change-name>/，并生成实现前所需的所有规划制品（proposal.md、specs、design.md、tasks.md），生成完成后即可进入开发阶段。
示例：
你：/opsx:propose add-dark-mode
AI：Created openspec/changes/add-dark-mode/
✓ proposal.md
✓ specs/ui/spec.md
✓ design.md
✓ tasks.md
Ready for implementation. Run /opsx:apply.
技巧：这是端到端开发最快的方式，若需要对制品进行分步控制，可切换扩展工作流使用/opsx:new + /opsx:continue。
2. /opsx:explore：开发前的“思路梳理器”
语法：/opsx:explore [topic]
参数为非必填，可传入需要调研的主题（如移动端认证方案）。
核心功能：无结构化的探索式对话，AI会调研代码库、对比多种实现方案、绘制可视化图表，帮你明确需求和技术方案，调研完成后可无缝过渡到/opsx:propose（默认）或/opsx:new（扩展工作流）。
示例：
你：/opsx:explore
AI：What would you like to explore?
你：How should we handle authentication for the mobile app?
AI：Let me investigate your current auth setup...
[分析代码库后给出3种方案并分析优劣]
技巧：需求模糊、需要调研技术方案时必用，此阶段不生成任何制品，可自由对比多种方案。
3. /opsx:apply：代码实现的“执行引擎”
语法：/opsx:apply [change-name]
参数为非必填，上下文可推断时可省略。
核心功能：读取变更文件夹中的tasks.md，识别未完成任务，逐个执行并编写代码、创建文件、运行测试，完成后会用[x]标记任务状态。
示例：
你：/opsx:apply
AI：Implementing add-dark-mode...
Reading tasks.md:
- [ ] 1.1 Create ThemeContext
- [ ] 1.2 Add CSS custom properties
[完成1.1后标记✓，继续执行后续任务]
技巧：中断后可自动恢复执行，多并行变更时可指定变更名明确执行目标，任务状态全程在tasks.md中追踪。
4. /opsx:archive：变更完成的“收尾工具”
语法：/opsx:archive [change-name]
参数为非必填，上下文可推断时可省略。
核心功能：检查制品和任务完成状态（任务未完成会警告但不阻塞），若增量规格未同步会提示同步，随后将变更文件夹迁移至openspec/changes/archive/YYYY-MM-DD-<name>/，留存所有制品作为审计痕迹。
示例：
你：/opsx:archive
AI：Archiving add-dark-mode...
检查制品和任务状态后提示：Delta specs: Not yet synced → Sync now? (recommended)
你：Yes
AI：✓ Synced specs to openspec/specs/ui/spec.md
✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
Change archived successfully.
技巧：归档前建议先执行/opsx:verify，提前发现代码实现与制品的不一致问题。
二、扩展工作流命令（复杂场景必备）
当开发场景复杂（如大型功能、团队协作），需要对开发流程精细化控制时，扩展工作流命令就是最佳选择，核心是分步控制、全程可审。
1. /opsx:new：变更的“脚手架初始化工具”
语法：/opsx:new [change-name] [--schema <schema-name>]
两个参数均非必填，未传入变更名会自动提示，schema默认使用spec-driven（也可在项目配置中设置）。
核心功能：创建变更文件夹和元数据文件.openspec.yaml，仅初始化脚手架，不生成任何规划制品，后续需通过/opsx:continue或/opsx:ff生成。
示例：
你：/opsx:new add-dark-mode
AI：Created openspec/changes/add-dark-mode/
Schema: spec-driven
Ready to create: proposal
Use /opsx:continue to create it, or /opsx:ff to create all artifacts.
技巧：变更名建议使用描述性名称（如fix-login-bug、refactor-module），避免使用update、changes等通用名称。
2. /opsx:continue：制品的“分步生成器”
语法：/opsx:continue [change-name]
参数为非必填，上下文可推断时可省略。
核心功能：查询制品依赖关系图，区分“已完成/可生成/被阻塞”的制品，仅生成第一个可生成的制品，读取依赖文件获取上下文，生成后提示下一个可生成的制品。
示例：
你：/opsx:continue
AI：Change: add-dark-mode
Artifact status:
✓ proposal (done)
◆ specs (ready)
○ tasks (blocked - needs: specs)
[生成specs后提示]
✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md
Now available: tasks
技巧：复杂变更必用，可在每个制品生成后审核修改，避免后续大规模调整，多个制品可能同时处于可生成状态。
3. /opsx:ff：制品的“快速生成器”
语法：/opsx:ff [change-name]
ff即Fast-forward，参数为非必填。
核心功能：按依赖关系一次性生成所有规划制品，通过待办列表追踪进度，生成完成后即可进入开发阶段，效果等同于/opsx:propose但基于/opsx:new的脚手架。
示例：
你：/opsx:ff add-dark-mode
AI：Fast-forwarding add-dark-mode...
✓ Creating proposal.md
✓ Creating specs/ui/spec.md
✓ Creating design.md
✓ Creating tasks.md
All planning artifacts complete!
技巧：需求明确的中等规模变更适用，比/opsx:continue更高效，生成后仍可编辑制品。
4. /opsx:verify：开发质量的“校验器”
语法：/opsx:verify [change-name]
参数为非必填，上下文可推断时可省略。
核心功能：从完整性、正确性、一致性三个维度验证代码实现与制品是否匹配，搜索代码库获取实现证据，将问题分为CRITICAL（严重）、WARNING（警告）、SUGGESTION（建议）三个等级，不阻塞归档但会暴露问题。
验证维度详解：
- 完整性：所有任务完成、需求落地、场景覆盖；
- 正确性：实现符合规格意图、边缘情况处理到位；
- 一致性：代码体现设计决策、编码模式统一。
技巧：归档前必执行，可发现代码与制品的“漂移”问题，警告不影响归档但建议修复，避免技术债务。
5. /opsx:sync：规格的“合并工具”
语法：/opsx:sync [change-name]
参数为非必填，上下文可推断时可省略。
核心功能：读取变更文件夹中的增量规格，解析增/删/改/重命名内容，合并到主规格目录openspec/specs/，保留未提及的原有内容，合并后变更仍处于活跃状态（不归档）。
技巧：此命令为可选，归档时会自动提示同步，仅在长周期变更、多并行变更需要最新主规格、需要单独预览合并效果时手动执行。
6. /opsx:bulk-archive：批量变更的“归档工具”
语法：/opsx:bulk-archive [change-names...]
参数为非必填，未传入会提示选择需要归档的变更。
核心功能：列出所有已完成变更，验证每个变更的状态，检测跨变更的规格冲突（通过调研代码库解决），按创建时间顺序归档，解决冲突后会提示合并结果。
示例：
你：/opsx:bulk-archive
AI：Found 3 completed changes: [列出变更及任务完成状态]
Checking for spec conflicts...
⚠ add-dark-mode and update-footer both touch specs/ui/
[调研后按时间顺序合并]
技巧：团队协作、多并行变更时适用，冲突解决基于实际代码实现，归档前会主动提示确认，避免覆盖规格内容。
7. /opsx:onboard：新手的“入门教程”
语法：/opsx:onboard
无参数，直接执行即可。
核心功能：基于你的实际代码库的交互式教程，引导完成完整的OpenSpec工作流，包括代码库分析、发现优化点、创建变更、生成制品、实现代码、验证、归档等全步骤，全程讲解每个操作的意义，生成的是真实的变更和代码（可保留或删除）。
技巧：OpenSpec新手必用，耗时15-30分钟，比看文档更易上手，基于真实项目而非测试示例，学习后可直接应用。
重要补充：不同AI工具的命令语法差异
OpenSpec命令的核心意图一致，但在不同AI编码助手中的语法略有差异，需根据使用工具调整，以下是主流工具的语法格式：
| AI工具 | 语法示例 |
|---|---|
| Claude Code | /opsx:propose、/opsx:apply |
| Cursor/Windsurf | /opsx-propose、/opsx-apply |
| Copilot（IDE） | /opsx-propose、/opsx-apply |
| Trae | /openspec-propose、/openspec-apply-change |
注意：GitHub Copilot的OpenSpec命令仅在IDE扩展（VS Code、JetBrains等）中可用，CLI版本暂不支持自定义提示文件。
兼容说明：遗留命令
OpenSpec保留了旧版“一步式”工作流的遗留命令，仍可使用但推荐使用新版OPSX命令，遗留命令及功能如下：
| 遗留命令 | 功能 |
|---|---|
/openspec:proposal | 一次性生成所有规划制品（proposal、specs、design、tasks） |
/openspec:apply | 执行变更的代码实现 |
/openspec:archive | 归档已完成的变更 |
适用场景：使用旧版工作流的现有项目、无需分步控制的极简变更、偏好“一步到位”开发方式的场景。 迁移说明：旧版变更可直接用新版OPSX命令继续开发，制品结构完全兼容，无迁移成本。
避坑指南：常见问题及解决方案
使用OpenSpec命令时可能遇到一些基础问题，官方文档提供了明确的解决方案，整理了4个高频问题，帮你快速排障：
1. 报错“Change not found”
原因：命令无法识别需要操作的变更。
解决方案：① 显式指定变更名（如/opsx:apply add-dark-mode）；② 用openspec list检查变更文件夹是否存在；③ 确认当前处于正确的项目目录。
2. 报错“No artifacts ready”
原因：所有制品均已完成或被依赖阻塞，无可用生成的制品。
解决方案：用openspec status --change <name>查看阻塞原因，创建缺失的依赖制品后再尝试。
3. 报错“Schema not found”
原因：指定的工作流schema不存在。
解决方案：① 用openspec schemas列出可用schema；② 检查schema名称拼写；③ 自定义schema可执行openspec schema init <name>创建。
4. 命令未被AI工具识别
原因：OpenSpec未初始化或技能未加载。
解决方案：① 执行openspec init初始化；② 执行openspec update重新生成技能；③ Claude Code需检查.claude/skills/目录是否存在；④ 重启AI工具加载新技能。
5. 制品生成不完整/错误
原因：项目上下文不足、变更描述不清晰、一次性生成过多制品。
解决方案：① 在openspec/config.yaml中添加项目上下文；② 为制品添加专属规则；③ 丰富变更描述的细节；④ 用/opsx:continue替代/opsx:ff分步生成。
总结：选对命令，让AI编码事半功倍
OpenSpec的命令体系核心是**“场景化、规范化、可追踪”**，通过这套命令，将AI编码的“随性”转化为可管理的工作流，既保留了AI编码的高效，又解决了代码质量、协作、可维护性等问题。
命令选择原则：
- 新手/简单需求/快速开发：用默认快速工作流（
/opsx:propose为核心）； - 复杂需求/团队协作/精细化控制：用扩展工作流（
/opsx:new为入口，配合/opsx:continue//opsx:ff//opsx:verify）； - 需求模糊：先执行
/opsx:explore调研，再启动变更； - 批量完成变更：用
/opsx:bulk-archive高效归档并处理冲突； - 首次使用：先执行
/opsx:onboard完成交互式教程。
掌握OpenSpec Commands，让AI编码助手成为“规范的开发助手”，而非“随性的代码生成器”，在提升开发效率的同时，保障代码质量和项目的可维护性。
