命令

这是 OpenSpec 斜杠命令的参考。这些命令在您的 AI 编码助手聊天界面（例如 Claude Code, Cursor, Windsurf）中调用。

关于工作流模式以及何时使用每个命令，请参阅 [[[[工作流]]]]。关于 CLI 命令，请参阅 [[[[CLI]]]]。

快速参考

命令	目的
`/opsx:explore`	在致力于变更之前思考想法
`/opsx:new`	开始新变更
`/opsx:continue`	基于依赖关系创建下一个工件
`/opsx:ff`	快进：一次性创建所有规划工件
`/opsx:apply`	实施变更中的任务
`/opsx:verify`	验证实施是否匹配工件
`/opsx:sync`	将增量规格合并到主规格
`/opsx:archive`	归档已完成的变更
`/opsx:bulk-archive`	一次归档多个变更
`/opsx:onboard`	完整工作流的引导式教程

命令参考

`/opsx:explore`

在致力于变更之前思考想法、调查问题并阐明需求。

语法：

/opsx:explore [topic]

参数：

参数	必填	描述
`topic`	否	您想要探索或调查的内容

它做什么：

开启一个无需结构的探索性对话
调查代码库以回答问题
给较选项和方法
创建图表以理清思路
当见解明晰时可以过渡到 /opsx:new

示例：

text

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle authentication for the mobile app?

AI:  Let me investigate your current auth setup...
     [Analyzes codebase]

     I see you're using session-based auth for the web app.
     For mobile, we have three main options:

     1. JWT tokens (stateless, works offline)
     2. OAuth2 (if you need third-party login)
     3. Extend current sessions (simpler, but requires connectivity)

     Your API already has CORS configured. Which direction interests you?

You: Let's go with JWT. Can we start a change for that?

AI:  Ready when you are. Run /opsx:new add-jwt-auth to begin.

提示：

当需求不清楚或需要调查时使用
探索期间不创建工件
适合在决定之前比较多种方法
可以读取文件并搜索代码库

`/opsx:new`

开始新变更。创建变更文件夹结构并使用选定的 Schema 进行脚手架搭建。

语法：

/opsx:new [change-name] [--schema <schema-name>]

参数：

参数	必填	描述
`change-name`	否	变更文件夹的名称（如果没有提供则提示）
`--schema`	否	使用的工作流 Schema（默认：来自配置或 `spec-driven`）

它做什么：

创建 openspec/changes/<change-name>/ 目录
在变更文件夹中创建 .openspec.yaml 元数据文件
显示准备创建的第一个工件模板
如果未提供，提示输入变更名称和 Schema

它创建了什么：

openspec/changes/<change-name>/
└── .openspec.yaml    # 变更元数据（Schema，创建日期）

示例：

You: /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.

提示：

使用描述性名称：add-feature, fix-bug, refactor-module
避免通用名称，如 update, changes, wip
Schema 也可以在项目配置中设置 (openspec/config.yaml)

`/opsx:continue`

创建依赖链中的下一个工件。一次创建一个工件以进行增量进展。

语法：

/opsx:continue [change-name]

参数：

参数	必填	描述
`change-name`	否	继续哪个变更（如果没有提供则从上下文中推断）

它做什么：

查询工件依赖图
显示哪些工件已就绪与受阻
创建第一个就绪的工件
读取依赖文件以获取上下文
显示创建后可用的内容

示例：

You: /opsx:continue

AI:  Change: add-dark-mode

     Artifact status:
     ✓ proposal    (done)
     ◆ specs       (ready)
     ◆ design      (ready)
     ○ tasks       (blocked - needs: specs)

     Creating specs...

     [Reads proposal.md, creates specs based on requirements]

     ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md

     Now available: tasks
     Run /opsx:continue to create the next artifact.

提示：

当您想在继续之前审查每个工件时使用
适合您想要控制的复杂变更
多个工件可能同时就绪
您可以在继续之前编辑已创建的工件

`/opsx:ff`

快进工件创建。一次性创建所有规划工件。

语法：

/opsx:ff [change-name]

参数：

参数	必填	描述
`change-name`	否	快进哪个变更（如果没有提供则从上下文中推断）

它做什么：

按依赖顺序创建所有工件
通过待办事项列表跟踪进度
当所有 apply-required 工件完成时停止
在创建下一个工件之前读取每个依赖项

示例：

You: /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!
     Ready for implementation. Run /opsx:apply to begin.

提示：

当您对要构建的内容有清晰的图景时使用
对于简单的变更比 /opsx:continue 更快
您之后仍然可以编辑工件
适合中小型功能

`/opsx:apply`

实施变更中的任务。处理任务列表，编写代码并勾选项目。

语法：

/opsx:apply [change-name]

参数：

参数	必填	描述
`change-name`	否	实施哪个变更（如果没有提供则从上下文中推断）

它做什么：

读取 tasks.md 并识别未完成的任务
逐个处理任务
编写代码，创建文件，根据需要运行测试
用复选框 [x] 标记任务完成

示例：

You: /opsx:apply

AI:  Implementing add-dark-mode...

     Reading tasks.md:
     - [ ] 1.1 Create ThemeContext
     - [ ] 1.2 Add CSS custom properties
     - [ ] 1.3 Implement localStorage persistence

     Working on 1.1: Create ThemeContext...
     [Creates src/context/ThemeContext.tsx]

     ✓ 1.1 Complete

     Working on 1.2: Add CSS custom properties...
     [Updates src/styles/globals.css]

     ✓ 1.2 Complete
     ...

提示：

如果中断，可以从停止的地方继续
通指定变更名称用于并行变更
完成状态在 tasks.md 复选框中跟踪

`/opsx:verify`

验证实施是否匹配您的变更工件。检查完整性、正确性和一致性。

语法：

/opsx:verify [change-name]

参数：

参数	必填	描述
`change-name`	否	验证哪个变更（如果没有提供则从上下文中推断）

它做什么：

检查三个维度的实施质量
搜索代码库以获取实施证据
报告分类为 CRITICAL（关键）、WARNING（警告）或 SUGGESTION（建议）的问题
不会阻止归档，但会提出问题

验证维度：

维度	它验证什么
完整性	所有任务完成，所有需求已实施，场景已覆盖
正确性	实施匹配规格意图，边缘情况已处理
一致性	设计决策反映在代码中，模式一致

示例：

You: /opsx:verify

AI:  Verifying add-dark-mode...

     COMPLETENESS
     ✓ All 8 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "System preference detection" has no test coverage

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "CSS variables" but implementation uses Tailwind classes

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for system preference detection
     2. Update design.md to reflect Tailwind usage, or refactor to use CSS variables

提示：

在归档之前运行以尽早发现不匹配
警告不会阻止归档，但表明潜在问题
适合在提交之前审查 AI 的工作
可以揭示工件与实施之间的偏差

`/opsx:sync`

可选命令。 将增量规格从变更合并到主规格。归档如果需要会提示同步，所以您通常不需要手动运行此命令。

语法：

/opsx:sync [change-name]

参数：

参数	必填	描述
`change-name`	否	同步哪个变更（如果没有提供则从上下文中推断）

它做什么：

从变更文件夹读取增量规格
解析 ADDED/MODIFIED/REMOVED/RENAMED 部分
将变更合并到主 openspec/specs/ 目录
保留未在增量中提到的现有内容
不归档变更（保持活动状态）

示例：

text

You: /opsx:sync

AI:  Syncing add-dark-mode delta specs...

     Reading: openspec/changes/add-dark-mode/specs/ui/spec.md
     Target:  openspec/specs/ui/spec.md

     Changes to apply:
     ✓ ADDED: Theme Selection requirement (2 scenarios)
     ✓ ADDED: Accessibility requirement (1 scenario)

     Merging...
     ✓ openspec/specs/ui/spec.md updated

     Change remains active. Run /opsx:archive when ready to complete.

何时手动使用：

场景	使用同步？
长期运行的变更，归档前需要更新主规格	是
多个并行变更需要更新的基础规格	是
想要单独预览/审查合并	是
快速变更，直接归档	否（归档处理它）

提示：

同步是智能的，不是复制粘贴
可以在不重复的情况下向现有需求添加场景
同步后变更保持活动状态（未归档）
大多数用户永远不需要直接调用此命令——如果需要，归档会提示

`/opsx:archive`

归档已完成的变更。完成变更并将其移至归档文件夹。

语法：

/opsx:archive [change-name]

参数：

参数	必填	描述
`change-name`	否	归档哪个变更（如果没有提供则从上下文中推断）

它做什么：

检查工件完成状态
检查任务完成情况（如果不完整则警告）
如果尚未同步，提供同步增量规格
将变更文件夹移动到 openspec/changes/archive/YYYY-MM-DD-<name>/
保留所有工件以备审计跟踪

示例：

text

You: /opsx:archive

AI:  Archiving add-dark-mode...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (8/8 tasks complete)

     Delta specs: Not yet synced
     → Sync now? (recommended)

You: 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 来发现问题

`/opsx:bulk-archive`

一次归档多个已完成的变更。处理变更之间的规格冲突。

语法：

/opsx:bulk-archive [change-names...]

参数：

参数	必填	描述
`change-names`	否	要归档的特定变更（如果没有提供则提示选择）

它做什么：

列出所有已完成的变更
归档前验证每个变更
检测跨变更的规格冲突
通过检查实际实施来解决冲突
按时间顺序归档

示例：

You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (8/8 tasks complete)
     - fix-login-bug (3/3 tasks complete)
     - update-footer (2/2 tasks complete)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will merge in chronological order:
     1. add-dark-mode (created Jan 20)
     2. update-footer (created Jan 22)

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-bug
     ✓ Archived update-footer
     Specs merged: add-dark-mode → update-footer

提示：

适合并行工作流
冲突解决是智能的（检查代码库）
变更按创建顺序归档
在覆盖规格内容之前提示

`/opsx:onboard`

OpenSpec 完整工作流的引导式入职。使用您的实际代码库的交互式教程。

语法：

/opsx:onboard

它做什么：

通过旁白引导完成完整的工作流周期
扫描您的代码库以寻找真正的改进机会
创建包含真实工件的实际变更
实施实际工作（小型、安全的变更）
归档已完成的变更
解释每一步发生的事情

阶段：

欢迎和代码库分析
寻找改进机会
创建变更 (/opsx:new)
编写提案
创建规格
编写设计
创建任务
实施任务 (/opsx:apply)
验证实施
归档变更
总结和后续步骤

示例：

You: /opsx:onboard

AI:  Welcome to OpenSpec!

     I'll walk you through the complete workflow using your actual codebase.
     We'll find something small to improve, create a proper change for it,
     implement it, and archive it.

     Let me scan your codebase for opportunities...

     [Analyzes codebase]

     I found a few things we could work on:
     1. Add input validation to the contact form
     2. Improve error messages in the auth flow
     3. Add loading states to async buttons

     Which interests you? (or suggest something else)

提示：

最适合学习工作流的新用户
使用真实代码，而非玩具示例
创建您可以保留或丢弃的真实变更
完成需要 15-30 分钟

AI 工具的命令语法

不同的 AI 工具使用略有不同的命令语法。使用与您的工具匹配的格式：

工具	语法示例
Claude Code	`/opsx:new`, `/opsx:apply`
Cursor	`/opsx-new`, `/opsx-apply`
Windsurf	`/opsx-new`, `/opsx-apply`
Copilot	`/opsx-new`, `/opsx-apply`
Trae	`/openspec-new-change`, `/openspec-apply-change`

无论语法如何，功能都是相同的。

遗留命令

这些命令使用旧的“一次性”工作流。它们仍然有效，但推荐使用 OPSX 命令。

命令	它做什么
`/openspec:proposal`	一次性创建所有工件（提案、规格、设计、任务）
`/openspec:apply`	实施变更
`/openspec:archive`	归档变更

何使用遗留命令：

使用旧工作流的现有项目
不需要增量工件创建的简单变更
偏好全有或全无的方法

迁移到 OPSX： 遗留变更可以使用 OPSX 命令继续。工件结构是兼容的。

故障排除

"Change not found"

命令无法识别要处理哪个变更。

解决方案：

显式指定变更名称：/opsx:apply add-dark-mode
检查变更文件夹是否存在：openspec list
验证您是否在正确的项目目录中

"No artifacts ready"

所有工件要么已完成，要么因缺少依赖项而受阻。

解决方案：

运行 openspec status --change <name> 查看受阻原因
检查所需工件是否存在
先创建缺失的依赖工件

"Schema not found"

指的 Schema 不存在。

解决方案：

列出可用 Schema：openspec schemas
检查 Schema 名称拼写
如果是自定义的，创建 Schema：openspec schema init <name>

Commands not recognized

AI 工具不识别 OpenSpec 命令。

解决方案：

确保 OpenSpec 已初始化：openspec init
重新生成 skills：openspec update
检查 .claude/skills/ 目录是否存在（对于 Claude Code）
重启您的 AI 工具以获取新 skills

Artifacts not generating properly

AI 创建不完整或不正确的工件。

解决方案：

在 openspec/config.yaml 中添加项目上下文
为特定指导添加每个工件规则
在变更描述中提更多细节
使用 /opsx:continue 代替 /opsx:ff 以获得更多控制

下一步

[[[[工作流]]]] - 常见模式以及何时使用每个命令
[[[[CLI]]]] - 用于管理和验证的终端命令
[[[[自定义]]]] - 创建自定义 Schemas 和工作流

brownfield

核心功能特性

命令

快速参考

命令参考

`/opsx:explore`

`/opsx:new`

`/opsx:continue`

`/opsx:ff`

`/opsx:apply`

`/opsx:verify`

`/opsx:sync`

`/opsx:archive`

`/opsx:bulk-archive`

`/opsx:onboard`

AI 工具的命令语法

遗留命令

故障排除

"Change not found"

"No artifacts ready"

"Schema not found"

Commands not recognized

Artifacts not generating properly

下一步

命令 ​

快速参考 ​

命令参考 ​

/opsx:explore ​

/opsx:new ​

/opsx:continue ​

/opsx:ff ​

/opsx:apply ​

/opsx:verify ​

/opsx:sync ​

/opsx:archive ​

/opsx:bulk-archive ​

/opsx:onboard ​

AI 工具的命令语法 ​

遗留命令 ​

故障排除 ​

"Change not found" ​

"No artifacts ready" ​

"Schema not found" ​

Commands not recognized ​

Artifacts not generating properly ​

下一步 ​

命令

快速参考

命令参考

`/opsx:explore`

`/opsx:new`

`/opsx:continue`

`/opsx:ff`

`/opsx:apply`

`/opsx:verify`

`/opsx:sync`

`/opsx:archive`

`/opsx:bulk-archive`

`/opsx:onboard`

AI 工具的命令语法

遗留命令

故障排除

"Change not found"

"No artifacts ready"

"Schema not found"

Commands not recognized

Artifacts not generating properly

下一步