指令
這是 OpenSpec 斜線指令的參考手冊。這些指令可在您的 AI 程式碼助理聊天介面中呼叫（例如 Claude Code、Cursor、Windsurf）。
關於工作流程模式及何時使用每個指令，請參閱 工作流程。關於 CLI 指令，請參閱 CLI。
快速參考
預設快速路徑（core 設定檔）
| 指令 | 用途 |
|---|---|
/opsx:propose | 一步驟建立變更並產生規劃產出物 |
/opsx:explore | 在提交變更前思考想法 |
/opsx:apply | 實作變更中的任務 |
/opsx:archive | 封存已完成的變更 |
擴展工作流程指令（自訂工作流程選擇）
| 指令 | 用途 |
|---|---|
/opsx:new | 開始新的變更腳手架 |
/opsx:continue | 根據依賴關係建立下一個產出物 |
/opsx:ff | 快速前進：一次建立所有規劃產出物 |
/opsx:verify | 驗證實作是否符合產出物 |
/opsx:sync | 將差異規格合併至主規格 |
/opsx:bulk-archive | 一次封存多個變更 |
/opsx:onboard | 引導式教學，涵蓋完整工作流程 |
預設全域設定檔為 core。若要啟用擴展工作流程指令，請執行 openspec config profile，選擇 workflows，然後在您的專案中執行 openspec update。
命令參考
/opsx:propose
一步到位地建立新的變更並產生規劃產物。這是 core 設定檔中的預設啟動命令。
語法：
text
/opsx:propose [變更名稱或描述]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
變更名稱或描述 | 否 | kebab-case 格式的名稱或自然語言的變更描述 |
功能：
- 建立
openspec/changes/<變更名稱>/目錄 - 產生實作前所需的產物（對於
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
在決定變更之前，先思考想法、調查問題並釐清需求。
語法：
/opsx:explore [主題]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
主題 | 否 | 您想要探索或調查的內容 |
功能：
- 開啟一個無需結構的探索性對話
- 調查程式碼庫以回答問題
- 比較選項與方法
- 建立視覺圖表以釐清思路
- 當想法具體化時，可過渡到
/opsx:propose（預設）或/opsx:new（擴充工作流程）
範例：
text
您：/opsx:explore
AI：您想探索什麼？
您：我們應該如何處理行動應用程式的身份驗證？
AI：讓我調查您目前的身份驗證設定...
[分析程式碼庫]
我看到您正在使用基於 Session 的網路應用程式身份驗證。
對於行動裝置，我們有三個主要選項：
1. JWT 權杖（無狀態，可離線運作）
2. OAuth2（如果您需要第三方登入）
3. 延伸目前的 Session（較簡單，但需要網路連線）
您的 API 已經配置了 CORS。您對哪個方向感興趣？
您：我們選擇 JWT。我們可以為此開始一個變更嗎？
AI：隨時為您準備就緒。請執行 /opsx:propose add-jwt-auth 開始。提示：
- 在需求不明確或需要調查時使用
- 探索期間不會建立任何產物
- 適合在決定前比較多種方法
- 可以讀取檔案並搜尋程式碼庫
/opsx:new
開始一個新的變更腳手架。建立變更資料夾，並等待您使用 /opsx:continue 或 /opsx:ff 來產生產物。
此命令屬於擴充工作流程集（不包含在預設的 core 設定檔中）。
語法：
/opsx:new [變更名稱] [--schema <架構名稱>]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
變更名稱 | 否 | 變更資料夾的名稱（若未提供則會提示） |
--schema | 否 | 要使用的工作流程架構（預設：來自設定或 spec-driven） |
功能：
- 建立
openspec/changes/<變更名稱>/目錄 - 在變更資料夾中建立
.openspec.yaml中繼資料檔案 - 顯示第一個準備好建立的產物範本
- 若未提供變更名稱和架構，則會提示輸入
建立的內容：
openspec/changes/<變更名稱>/
└── .openspec.yaml # 變更中繼資料（架構、建立日期）範例：
您：/opsx:new add-dark-mode
AI：已建立 openspec/changes/add-dark-mode/
架構：spec-driven
準備建立：提案
使用 /opsx:continue 來建立，或使用 /opsx:ff 來建立所有產物。提示：
- 使用描述性名稱：
add-feature、fix-bug、refactor-module - 避免使用通用名稱如
update、changes、wip - 架構也可以在專案設定中設定（
openspec/config.yaml）
/opsx:continue
建立依賴鏈中的下一個產物。一次建立一個產物以實現增量進度。
語法：
/opsx:continue [變更名稱]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
變更名稱 | 否 | 要繼續哪個變更（若未提供則從上下文推斷） |
功能：
- 查詢產物依賴圖
- 顯示哪些產物已準備好 vs 被阻塞
- 建立第一個準備好的產物
- 讀取依賴檔案以獲取上下文
- 顯示建立後哪些產物變得可用
範例：
您：/opsx:continue
AI：變更：add-dark-mode
產物狀態：
✓ 提案 （已完成）
◆ 規格 （已準備好）
◆ 設計 （已準備好）
○ 任務 （被阻塞 - 需要：規格）
正在建立規格...
[讀取 proposal.md，根據需求建立規格]
✓ 已建立 openspec/changes/add-dark-mode/specs/ui/spec.md
現在可用：任務
請執行 /opsx:continue 來建立下一個產物。提示：
- 在您想於繼續前審查每個產物時使用
- 適合需要控制權的複雜變更
- 多個產物可能同時變得可用
- 您可以在繼續前編輯已建立的產物
/opsx:ff
快速推進產物建立。一次建立所有規劃產物。
語法：
/opsx:ff [變更名稱]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
變更名稱 | 否 | 要快速推進哪個變更（若未提供則從上下文推斷） |
功能：
- 按依賴順序建立所有產物
- 透過待辦清單追蹤進度
- 當所有
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 [變更名稱]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
變更名稱 | 否 | 要實作哪個變更（若未提供則從上下文推斷） |
功能：
- 讀取
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:verify
驗證實作是否符合您的變更產物。檢查完整性、正確性和一致性。
語法：
/opsx:verify [變更名稱]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
變更名稱 | 否 | 要驗證哪個變更（若未提供則從上下文推斷） |
功能：
- 檢查實作品質的三個維度
- 搜尋程式碼庫中的實作證據
- 報告分類為 CRITICAL、WARNING 或 SUGGESTION 的問題
- 不會阻塞歸檔，但會顯示問題
驗證維度：
| 維度 | 驗證內容 |
|---|---|
| 完整性 | 所有任務完成、所有需求已實作、涵蓋所有情境 |
| 正確性 | 實作符合規格意圖、處理邊界情況 |
| 一致性 | 設計決策反映在程式碼中、模式一致 |
範例：
您：/opsx:verify
AI：正在驗證 add-dark-mode...
完整性
✓ tasks.md 中的所有 8 個任務已勾選
✓ 規格中的所有需求都有對應的程式碼
⚠ 情境「系統偏好偵測」沒有測試覆蓋
正確性
✓ 實作符合規格意圖
✓ 處理了情境中的邊界情況
✓ 錯誤狀態符合規格定義
一致性
✓ 設計決策反映在程式碼結構中
✓ 命名慣例與 design.md 一致
⚠ 設計提到「CSS 變數」但實作使用 Tailwind 類別
摘要
─────────────────────────────
嚴重問題：0
警告：2
可以歸檔：是（有警告）
建議：
1. 為系統偏好偵測新增測試
2. 更新 design.md 以反映 Tailwind 使用，或重構為使用 CSS 變數提示：
- 在歸檔前執行以提早發現不匹配
- 警告不會阻塞歸檔，但表示潛在問題
- 適合在提交前審查 AI 的工作
- 可以揭示產物與實作之間的偏差
/opsx:sync
可選命令。 將變更中的差異規格合併到主規格中。歸檔時會提示是否需要同步，因此通常不需要手動執行此命令。
語法：
/opsx:sync [變更名稱]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
變更名稱 | 否 | 要同步哪個變更（若未提供則從上下文推斷） |
功能：
- 從變更資料夾讀取差異規格
- 解析 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。何時手動使用：
| 情境 | 使用同步？ |
|---|---|
| 長期變更，想在歸檔前將規格納入主規格 | 是 |
| 多個並行變更需要更新的基礎規格 | 是 |
| 想預覽/單獨審查合併結果 | 是 |
| 快速變更，直接歸檔 | 否（歸檔會處理） |
提示：
- 同步是智慧的，不是複製貼上
- 可以將情境新增到現有需求而不重複
- 同步後變更保持啟用狀態（未歸檔）
- 大多數使用者永遠不需要直接呼叫此命令—歸檔時會提示是否需要
/opsx:archive
歸檔已完成的變更。完成變更並將其移至歸檔資料夾。
語法：
/opsx:archive [變更名稱]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
變更名稱 | 否 | 要歸檔哪個變更（若未提供則從上下文推斷） |
功能：
- 檢查產物完成狀態
- 檢查任務完成情況（若未完成則警告）
- 如果尚未同步，提供同步差異規格的選項
- 將變更資料夾移至
openspec/changes/archive/YYYY-MM-DD-<名稱>/ - 保留所有產物以供稽核
範例：
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 [變更名稱...]參數：
| 參數 | 必要 | 描述 |
|---|---|---|
變更名稱 | 否 | 要歸檔的特定變更（若未提供則提示選擇） |
功能：
- 列出所有已完成的變更
- 在歸檔前驗證每個變更
- 偵測跨變更的規格衝突
- 透過檢查實際實作的內容來解決衝突
- 按時間順序歸檔
範例：
您：/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功能：
- 透過解說引導完成完整的工作流程週期
- 掃描您的程式碼庫以尋找真實的改進機會
- 建立一個帶有真實產物的實際變更
- 實作實際工作（小型、安全的變更）
- 歸檔已完成的變更
- 在每個步驟發生時進行解釋
階段：
- 歡迎與程式碼庫分析
- 尋找改進機會
- 建立變更（
/opsx:new） - 撰寫提案
- 建立規格
- 撰寫設計
- 建立任務
- 實作任務（
/opsx:apply） - 驗證實作
- 歸檔變更
- 摘要與後續步驟
範例：
您：/opsx:onboard
AI：歡迎使用 OpenSpec！
我將使用您的實際程式碼庫引導您完成完整的工作流程。
我們將尋找一些小型的改進項目，為其建立適當的變更，
實作它，然後歸檔它。
讓我掃描您的程式碼庫以尋找機會...
[分析程式碼庫]
我找到了一些我們可以處理的項目：
1. 為聯絡表單新增輸入驗證
2. 改進身份驗證流程中的錯誤訊息
3. 為非同步按鈕新增載入狀態
您對哪個感興趣？（或建議其他項目）提示：
- 最適合學習工作流程的新使用者
- 使用真實程式碼，而非虛擬範例
- 建立一個您可以保留或捨棄的真實變更
- 需要 15-30 分鐘完成
各 AI 工具的指令語法
不同的 AI 工具使用略有差異的指令語法。請根據您使用的工具選擇對應格式：
| 工具 | 語法範例 |
|---|---|
| Claude Code | /opsx:propose、/opsx:apply |
| Cursor | /opsx-propose、/opsx-apply |
| Windsurf | /opsx-propose、/opsx-apply |
| Copilot (IDE) | /opsx-propose、/opsx-apply |
| Trae | 基於技能的調用，例如 /openspec-propose、/openspec-apply-change（不會生成 opsx-* 指令檔案） |
各工具的意圖相同，但指令的呈現方式可能因整合方式而異。
注意： 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以獲得更多控制權