指令
這是 OpenSpec 斜線指令的參考文件。這些指令可在您的 AI 程式碼助手的聊天介面中調用（例如 Claude Code、Cursor、Devin Desktop）。
關於工作流程模式及何時使用各指令，請參閱 工作流程。關於 CLI 指令，請參閱 CLI。
這些頁面使用 /opsx:<command> 作為標準名稱。部分工具的寫法不同——Cursor 和 GitHub Copilot 註冊的是 /opsx-propose，Codex 使用的是 $openspec-propose——請針對您的工具查看 如何調用。OpenSpec 產生的檔案已使用正確的格式。
快速參考
預設快速路徑（core 設定檔）
| 指令 | 用途 |
|---|---|
/opsx:propose | 建立變更並一步生成規劃產物 |
/opsx:explore | 在提交變更前深入思考構想 |
/opsx:apply | 實作變更中的任務 |
/opsx:update | 修訂變更的規劃產物並保持其一致性 |
/opsx:sync | 將增量規格合併至主要規格 |
/opsx:archive | 歸檔已完成的變更 |
擴展工作流程指令（自訂工作流程選擇）
| 指令 | 用途 |
|---|---|
/opsx:new | 啟動新的變更架構 |
/opsx:continue | 根據依賴關係建立下一個產物 |
/opsx:ff | 快轉：一次建立所有規劃產物 |
/opsx:verify | 驗證實作與產物相符 |
/opsx:bulk-archive | 一次歸檔多個變更 |
/opsx:onboard | 引導式教學，涵蓋完整工作流程 |
預設全域設定檔為 core。若要啟用擴展工作流程指令，請執行 openspec config profile，選擇工作流程，然後在專案中執行 openspec update。
命令參考
/opsx:propose
一次性建立新變更並生成規劃工件。這是 core 設定檔中的預設起始命令。
語法：
text
/opsx:propose [change-name-or-description]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
change-name-or-description | 否 | Kebab-case 名稱或自然語言的變更描述 |
功能：
- 建立
openspec/changes/<change-name>/ - 生成實施前所需的工件（針對
spec-driven：提案、規格、設計、任務） - 當變更準備好執行
/opsx:apply時停止
範例：
text
你: /opsx:propose add-dark-mode
AI: 已建立 openspec/changes/add-dark-mode/
✓ proposal.md
✓ specs/ui/spec.md
✓ design.md
✓ tasks.md
已準備好進行實施。請執行 /opsx:apply。提示：
- 使用此命令可獲得最快的端到端路徑
- 如果您希望逐步控制工件，請啟用擴展工作流並使用
/opsx:new+/opsx:continue
/opsx:explore
不確定從何處開始時，請由此入手。 Explore 是一個無風險的思考夥伴：它會讀取您的程式碼庫，比較選項，並在變更存在之前將模糊的想法精煉為具體計劃。它包含在預設設定檔中。如需完整案例和更多範例，請參閱 Explore First 指南。
在承諾進行變更之前，先思考想法、調查問題並釐清需求。
語法：
/opsx:explore [topic]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
topic | 否 | 您想要探索或調查的內容 |
功能：
- 開啟無需結構的探索性對話
- 調查程式碼庫以回答問題
- 比較選項和方法
- 建立視覺圖表以釐清思路
- 當見解明確時，可以轉換到
/opsx:propose（預設）或/opsx:new（擴展工作流）
範例：
text
你: /opsx:explore
AI: 您想要探索什麼？
你: 我們該如何處理行動應用程式的身分驗證？
AI: 讓我調查您目前的身分驗證設置...
[分析程式碼庫]
我看到您對網頁應用程式使用基於 session 的身分驗證。
對於行動裝置，我們有三個主要選項：
1. JWT tokens（無狀態，離線可用）
2. OAuth2（如果需要第三方登入）
3. 擴展現有的 sessions（更簡單，但需要連線）
您的 API 已經配置了 CORS。您對哪個方向感興趣？
你: 我們選擇 JWT。我們可以為此啟動一個變更嗎？
AI: 隨時準備就緒。請執行 /opsx:propose add-jwt-auth 以開始。提示：
- 當需求不明確或您需要調查時使用
- 探索期間不會創建任何工件
- 適合在決定之前比較多種方法
- 可以讀取檔案並搜尋程式碼庫
/opsx:new
啟動新的變更骨架。建立變更資料夾並等待您使用 /opsx:continue 或 /opsx:ff 生成工件。
此命令屬於擴展工作流集（不包含在預設 core 設定檔中）。
語法：
/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, 建立日期)範例：
你: /opsx:new add-dark-mode
AI: 已建立 openspec/changes/add-dark-mode/
Schema: spec-driven
準備創建：proposal
使用 /opsx:continue 來創建它，或使用 /opsx:ff 來創建所有工件。提示：
- 使用描述性名稱：
add-feature、fix-bug、refactor-module - 避免使用通用名稱如
update、changes、wip - Schema 也可以在專案配置中設置 (
openspec/config.yaml)
/opsx:continue
在依賴鏈中創建下一個工件。一次創建一個工件以實現增量進展。
語法：
/opsx:continue [change-name]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
change-name | 否 | 要繼續的變更（若未提供則根據上下文推斷） |
功能：
- 查詢工件依賴圖
- 顯示哪些工件已就緒 vs 被阻塞
- 創建第一個就緒的工件
- 讀取依賴文件以獲取上下文
- 顯示創建後哪些內容變為可用
範例：
你: /opsx:continue
AI: 變更：add-dark-mode
工件狀態：
✓ proposal (已完成)
◆ specs (就緒)
◆ design (就緒)
○ tasks (阻塞 - 需要：specs, design)
正在創建 specs...
[讀取 proposal.md，根據需求創建 specs]
✓ 已建立 openspec/changes/add-dark-mode/specs/ui/spec.md
現在可用：design
請執行 /opsx:continue 來創建下一個工件。提示：
- 當您希望在繼續之前審查每個工件時使用
- 適合您希望控制的複雜變更
- 多個工件可能同時變為就緒
- 您可以在繼續之前編輯已創建的工件
/opsx:ff
快速通過工件創建。一次性創建所有規劃工件。
語法：
/opsx:ff [change-name]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
change-name | 否 | 要快速前進的變更（若未提供則根據上下文推斷） |
功能：
- 按依賴順序創建所有工件
- 透過待辦事項清單追蹤進度
- 當所有
apply-required工件完成時停止 - 在創建下一個工件之前讀取每個依賴項
範例：
你: /opsx:ff add-dark-mode
AI: 正在快速前進 add-dark-mode...
✓ 正在創建 proposal.md
✓ 正在創建 specs/ui/spec.md
✓ 正在創建 design.md
✓ 正在創建 tasks.md
所有規劃工件已完成！
已準備好進行實施。請執行 /opsx:apply 以開始。提示：
- 當您清楚知道要構建什麼時使用
- 對於簡單的變更，比
/opsx:continue更快 - 您仍然可以在之後編輯工件
- 適合中小型功能
/opsx:apply
實施變更中的任務。遍歷任務清單，編寫代碼並勾選項目。
語法：
/opsx:apply [change-name]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
change-name | 否 | 要實施的變更（若未提供則根據上下文推斷） |
功能：
- 讀取
tasks.md並識別未完成的任務 - 逐一處理任務
- 按需編寫代碼、創建檔案、運行測試
- 使用複選框
[x]標記任務完成
範例：
你: /opsx:apply
AI: 正在實施 add-dark-mode...
讀取 tasks.md：
- [ ] 1.1 建立 ThemeContext
- [ ] 1.2 添加 CSS 自定義屬性
- [ ] 1.3 實施 localStorage 持久化
正在處理 1.1：建立 ThemeContext...
[建立 src/context/ThemeContext.tsx]
✓ 1.1 完成
正在處理 1.2：添加 CSS 自定義屬性...
[更新 src/styles/globals.css]
✓ 1.2 完成
...提示：
- 如果被打斷，可以從上次停下的地方恢復
- 通過指定變更名稱來用於平行變更
- 完成狀態追蹤在
tasks.md的複選框中
/opsx:update
修訂變更現有的規劃工件，並保持它們之間的一致性。僅限規劃工件——它從未編輯過代碼。
語法：
text
/opsx:update [change-name]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
change-name | 否 | 要更新的變更（若未提供則根據上下文推斷） |
功能：
- 透過
openspec status --change <name> --json讀取變更的工件 - 應用您請求的修訂，或者如果您沒有指定某個修訂，則檢查工件是否存在矛盾
- 以任何方向調和其他現有工件（設計編輯可能會反饋影響提案）
- 在寫入之前與您確認每次編輯，一次一個工件
- 最後建議下一步：
/opsx:continue（缺少工件）、/opsx:apply（將修訂後的計劃帶入代碼）或/opsx:archive（全部完成）
範例：
text
你: /opsx:update add-dark-mode - 我們現在將主題存儲在 cookie 中，而不是 localStorage
AI: 正在讀取 add-dark-mode 工件...
設計中有兩處引用了 localStorage；任務 1.3 涵蓋了
localStorage 持久化；提案中未提及存儲。
擬議修訂：
1. design.md - 將 localStorage 決策替換為 cookie 存儲
2. tasks.md - 重述任務 1.3 為 cookie 持久化
應用修訂 1？(design.md)提示：
- 它不會創建缺失的工件——那是
/opsx:continue的工作 - 如果變更已經實施，請跟進執行
/opsx:apply以便代碼與修訂後的計劃匹配 - 如果您的修訂改變了變更的意圖，請用新的變更重新開始（參閱 何時更新 vs. 重新開始）
/opsx:verify
驗證實施是否符合您的變更工件。檢查完整性、正確性和一致性。
語法：
/opsx:verify [change-name]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
change-name | 否 | 要驗證的變更（若未提供則根據上下文推斷） |
功能：
- 檢查實施質量的三個維度
- 在程式碼庫中搜尋實施證據
- 報告分類為 CRITICAL（嚴重）、WARNING（警告）或 SUGGESTION（建議）的問題
- 不會阻止歸檔，但會顯示問題
驗證維度：
| 維度 | 驗證內容 |
|---|---|
| 完整性 | 所有任務完成，所有需求已實施，場景已覆蓋 |
| 正確性 | 實施符合規格意圖，邊界情況已處理 |
| 一致性 | 設計決策反映在代碼中，模式一致 |
範例：
你: /opsx:verify
AI: 正在驗證 add-dark-mode...
完整性
✓ tasks.md 中的所有 8 個任務均已勾選
✓ specs 中的所有需求都有對應的代碼
⚠ 場景「系統偏好檢測」沒有測試覆蓋率
正確性
✓ 實施符合規格意圖
✓ 已處理場景中的邊界情況
✓ 錯誤狀態符合規格定義
一致性
✓ 設計決策反映在代碼結構中
✓ 命名慣例與 design.md 一致
⚠ 設計提到「CSS 變量」但實施使用了 Tailwind 類
摘要
─────────────────────────────
嚴重問題：0
警告：2
準備歸檔：是（帶有警告）
建議：
1. 為系統偏好檢測添加測試
2. 更新 design.md 以反映 Tailwind 的使用，或重構以使用 CSS 變量提示：
- 在歸檔之前運行以及早發現不匹配
- 警告不會阻止歸檔，但表示潛在問題
- 適合在提交之前審查 AI 的工作
- 可以揭示工件與實施之間的漂移
/opsx:sync
可選命令。 將變更中的差異規格合併到主規格中。歸檔會在需要時提示同步，因此您通常不需要手動運行此命令。
語法：
/opsx:sync [change-name]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
change-name | 否 | 要同步的變更（若未提供則根據上下文推斷） |
功能：
- 從變更資料夾讀取差異規格
- 解析 ADDED/MODIFIED/REMOVED/RENAMED 部分
- 將更改合併到主
openspec/specs/目錄中 - 保留差異中未提到的現有內容
- 不會歸檔變更（保持活動狀態）
範例：
text
你: /opsx:sync
AI: 正在同步 add-dark-mode 差異規格...
讀取：openspec/changes/add-dark-mode/specs/ui/spec.md
目標： openspec/specs/ui/spec.md
要應用的更改：
✓ 新增：主題選擇要求（2 個場景）
✓ 新增：無障礙要求（1 個場景）
正在合併...
✓ openspec/specs/ui/spec.md 已更新
變更保持活動狀態。準備好完成時請執行 /opsx:archive。何時手動使用：
| 場景 | 使用 sync？ |
|---|---|
| 長期運行的變更，希望在歸檔前將規格放入主分支 | 是 |
| 多個平行變更需要更新的基礎規格 | 是 |
| 想要單獨預覽/審查合併 | 是 |
| 快速變更，直接歸檔 | 否（歸檔會處理） |
提示：
- Sync 是智能的，不是複製貼上
- 可以向現有要求添加場景而不重複
- 同步後變更保持活動狀態（未歸檔）
- 大多數用戶永遠不需要直接調用此命令——如果需要，歸檔會提示
/opsx:archive
歸檔已完成的變更。終止變更並將其移至歸檔資料夾。
語法：
/opsx:archive [change-name]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
change-name | 否 | 要歸檔的變更（若未提供則根據上下文推斷） |
功能：
- 檢查工件完成狀態
- 檢查任務完成情況（如果不完整則警告）
- 如果尚未同步，提供同步差異規格的選項
- 將變更資料夾移動到
openspec/changes/archive/YYYY-MM-DD-<name>/ - 保留所有工件以供審計軌跡
範例：
text
你: /opsx:archive
AI: 正在歸檔 add-dark-mode...
工件狀態：
✓ proposal.md 存在
✓ specs/ 存在
✓ design.md 存在
✓ tasks.md 存在（8/8 任務完成）
差異規格：尚未同步
→ 立即同步？（推薦）
你: 是
AI: ✓ 已將規格同步至 openspec/specs/ui/spec.md
✓ 已移動至 openspec/changes/archive/2025-01-24-add-dark-mode/
變更已成功歸檔。提示：
- 歸檔不會因不完整的任務而阻止，但會發出警告
- 差異規格可以在歸檔期間或之前同步
- 歸檔的變更會保留以供歷史記錄
- 建議先使用
/opsx:verify來發現問題
/opsx:bulk-archive
一次性歸檔多個已完成的變更。處理變更之間的規格衝突。
語法：
/opsx:bulk-archive [change-names...]參數：
| 參數 | 必要 | 說明 |
|---|---|---|
change-names | 否 | 要歸檔的特定變更（若未提供則提示選擇） |
功能：
- 列出所有已完成的變更
- 在歸檔之前驗證每個變更
- 檢測變更之間的規格衝突
- 通過檢查實際實施的內容來解決衝突
- 按時間順序歸檔
範例：
你: /opsx:bulk-archive
AI: 找到 3 個已完成的變更：
- add-dark-mode（8/8 任務完成）
- fix-login-bug（3/3 任務完成）
- update-footer（2/2 任務完成）
正在檢查規格衝突...
⚠ add-dark-mode 和 update-footer 都觸及 specs/ui/
正在檢查程式碼庫以解決...
兩個變更都已實施。將按時間順序合併：
1. add-dark-mode（1月20日建立）
2. update-footer（1月22日建立）
歸檔所有 3 個變更？
你: 是
AI: ✓ 已歸檔 add-dark-mode
✓ 已歸檔 fix-login-bug
✓ 已歸檔 update-footer
規格已合併：add-dark-mode → update-footer提示：
- 適合平行工作流
- 衝突解決是代理式的（檢查程式碼庫）
- 變更按建立順序歸檔
- 在覆蓋規格內容之前會提示
/opsx:onboard
引導式 OpenSpec 工作流入門。使用您實際的程式碼庫進行互動式教程。
語法：
/opsx:onboard功能：
- 通過敘述 walkthrough 完整的工作流週期
- 掃描您的程式碼庫以尋找真正的改進機會
- 創建一個具有真實工件的實際變更
- 實施實際工作（小型、安全的變更）
- 歸檔已完成的變更
- 在發生時解釋每個步驟
階段：
- 歡迎和程式碼庫分析
- 尋找改進機會
- 創建變更 (
/opsx:new) - 撰寫提案
- 創建規格
- 撰寫設計
- 創建任務
- 實施任務 (
/opsx:apply) - 驗證實施
- 歸檔變更
- 總結和後續步驟
範例：
你: /opsx:onboard
AI: 歡迎來到 OpenSpec！
我將使用您實際的程式碼庫為您 walkthrough 完整的工作流。
我們將找到一些小的改進點，為其創建適當的變更，
實施它，然後歸檔它。
讓我掃描您的程式碼庫以尋找機會...
[分析程式碼庫]
我找到了幾個我們可以處理的事情：
1. 為聯繫表單添加輸入驗證
2. 改善身分驗證流程中的錯誤消息
3. 為異步按鈕添加加載狀態
您對哪一個感興趣？（或提出其他建議）提示：
- 最適合學習工作流的新用戶
- 使用真實代碼，而非玩具範例
- 創建一個您可以保留或丟棄的真實變更
- 完成需要 15-30 分鐘
各 AI 工具的指令語法
不同的 AI 工具使用略有差異的指令語法。請使用與您工具相符的格式：
| 您工具的指令檔案 | 語法範例 | 範例工具 |
|---|---|---|
.../commands/opsx/<id>.* | /opsx:propose、/opsx:apply | Claude Code、Gemini CLI、Crush |
.../opsx-<id>.* | /opsx-propose、/opsx-apply | Cursor、Devin Desktop、Copilot (IDE)、Trae、Oh My Pi |
| 無 — 僅限技能 | /openspec-propose、/openspec-apply-change | CodeArts、ForgeCode、Hermes、MiniMax Code、Mistral Vibe、Zed Agent、共用 .agents |
| 無 — Kimi Code | /skill:openspec-propose | Kimi Code |
| 無 — Codex CLI | $openspec-propose | Codex |
Devin Desktop 與 Devin Local 的差異：
.devin/workflows/opsx-*.md檔案為 Devin Desktop 提供/opsx-propose。Devin Local 沒有工作流程 — 請使用 OpenSpec 寫入.devin/skills/的技能，例如/openspec-propose，這些技能在兩個代理上都能使用。
各工具的意圖相同，但指令的呈現方式可能因整合方式而異。如何調用 列出了所有支援的工具；此表格僅展示各形狀的範例。
注意： GitHub Copilot 指令（
.github/prompts/*.prompt.md）僅在 IDE 延伸功能（VS Code、JetBrains、Visual Studio）中可用。GitHub Copilot CLI 目前不支援自訂提示檔案 — 請參閱 支援的工具 了解詳細資訊與替代方案。
舊版指令
這些指令使用較早的「一次性完成」工作流程。它們仍然可用，但建議使用 OPSX 指令。
| 指令 | 功能說明 |
|---|---|
/openspec:proposal | 一次性建立所有產出物（提案、規格、設計、任務） |
/openspec:apply | 實作變更 |
/openspec:archive | 封存變更 |
何時使用舊版指令：
- 使用舊工作流程的現有專案
- 不需要逐步建立產出物的簡單變更
- 偏好全有或全無的方式
遷移至 OPSX： 舊版變更可以使用 OPSX 指令繼續進行。產出物結構是相容的。
疑難排解
「找不到變更」
指令無法識別要處理哪個變更。
解決方案：
- 明確指定變更名稱：
/opsx:apply add-dark-mode - 確認變更資料夾存在：
openspec list - 確認您在正確的專案目錄中
「沒有準備好的產出物」
所有產出物已完成或被缺少的前置相依所阻擋。
解決方案：
- 執行
openspec status --change <name>查看阻擋原因 - 檢查所需的產出物是否存在
- 先建立缺少的前置相依產出物
「找不到 Schema」
指定的 schema 不存在。
解決方案：
- 列出可用的 schema：
openspec schemas - 檢查 schema 名稱的拼寫
- 如果是自訂 schema，請建立它：
openspec schema init <name>
指令未被識別
AI 工具無法識別 OpenSpec 指令。
解決方案：
- 確認 OpenSpec 已初始化：
openspec init - 重新產生技能：
openspec update - 確認
.claude/skills/目錄存在（適用於 Claude Code） - 重新啟動 AI 工具以載入新技能
產出物未正確產生
AI 建立的產出物不完整或不正確。
解決方案：
- 在
openspec/config.yaml中加入專案上下文 - 為特定產出物加入規則以提供具體指引
- 在變更描述中提供更多細節
- 使用
/opsx:continue取代/opsx:ff以獲得更多控制