OpenSpec

指令如何運作 ​

唯一需要知道的事：OpenSpec 有兩種指令，它們在兩個不同的地方執行。

  • openspec ... 指令在您的終端機中執行。（例如：openspec init。）
  • /opsx:... 指令在您的AI 助手的聊天視窗中執行。（例如：/opsx:propose。）

如果您曾經在終端機中輸入 /opsx:propose 卻什麼都沒發生，這就是原因。您正在跟 OpenSpec 錯誤的那一半對話。斜線指令不是終端機指令。它們是您給 AI 編碼助手的指示，就在您平時輸入「新增一個登入表單」的那個聊天框裡。

這個單一區分是新使用者最常遇到的障礙，所以我們來把它說得清清楚楚。

兩個部分 ​

OpenSpec 是一個身兼兩職的專案。

CLI（終端機部分）。 一個名為 openspec 的程式，您從 shell 安裝並執行它。它負責設定您的專案、列出和驗證變更、顯示儀表板，以及歸檔已完成的工作。您會在 iTerm、VS Code 終端機、PowerShell 等任何您會執行 git 或 npm 的地方輸入這些指令。

bash
openspec init        # 在此專案中設定 OpenSpec
openspec list        # 查看進行中的變更
openspec view        # 開啟互動式儀表板

斜線指令（聊天部分）。 像 /opsx:propose 和 /opsx:apply 這樣的簡短指令，您輸入到 AI 助手中。它們告訴 AI 遵循 OpenSpec 工作流程：草擬提案、撰寫規格、根據任務清單建置、完成後歸檔。您會在 Claude Code、Cursor、Devin Desktop、Copilot 或您使用的任何助手中輸入這些指令。

text
/opsx:propose add-dark-mode    （在您的 AI 聊天中輸入）
/opsx:apply                    （在您的 AI 聊天中輸入）
/opsx:archive                  （在您的 AI 聊天中輸入）

以下是心智模型的一張圖：

text
        您的終端機                         您的 AI 助手聊天視窗
   ┌──────────────────────┐               ┌──────────────────────────────┐
   │  $ openspec init     │   安裝        │  /opsx:propose add-dark-mode  │
   │  $ openspec list     │  ──────────►  │  /opsx:apply                  │
   │  $ openspec view     │   指令        │  /opsx:archive                │
   └──────────────────────┘    與技能     └──────────────────────────────┘
        在此執行 openspec                       在此執行 /opsx:*

注意箭頭。在終端機中執行 openspec init 就是將斜線指令安裝到您的 AI 工具中。終端機部分設定聊天部分。之後，日常操作主要發生在聊天中。

「如何啟動互動模式？」 ​

沒有獨立的互動模式需要啟動。 這個問題經常出現，所以值得給一個明確的答案。

您不需要進入特殊的 OpenSpec 模式。您只需像平常一樣開啟您的 AI 編碼助手，然後在聊天中輸入斜線指令。斜線指令就是您「進入」OpenSpec 的方式。您的助手會識別它，載入對應的 OpenSpec 技能，然後開始遵循工作流程。

所以真正的步驟是：

  1. 在您的專案中開啟 AI 編碼助手（Claude Code、Cursor、Devin Desktop 等）。
  2. 在它的聊天中輸入 /opsx:propose，就在您輸入任何其他請求的地方。
  3. 觀察自動補全：如果 OpenSpec 已安裝，當您輸入斜線時，您會看到 /opsx:propose、/opsx:apply 等建議出現。

就這樣。沒有需要切換的模式，沒有需要啟動的守護程序，沒有獨立的視窗。

有一件事確實是互動式的，而且存在於終端機中：openspec view。它會開啟一個儀表板供您瀏覽規格和變更。但那是一個檢視器，不是您用來提案和建置的工具。建置是透過聊天中的斜線指令進行的。

為什麼要這樣分拆 ​

理解這一點很重要，因為它解釋了為什麼 OpenSpec 能與 30 多種不同的 AI 工具協作。

CLI 是引擎。它了解規則：變更資料夾的結構、哪些產物依賴哪些、如何將增量規格合併到您的來源真相中。它在任何地方都是相同的。

斜線指令是方向盤，而每個 AI 工具的方向盤都略有不同。Claude Code 稱它們為 commands。Cursor 和 Devin Desktop 有自己的格式。有些工具稱它們為 skills。當您執行 openspec init 時，OpenSpec 會為您選擇的每個工具生成正確類型的檔案，因此無論您偏好哪個助手，相同的 /opsx:propose 意圖都能運作。

這個設計的優勢：您只需學習一次工作流程，就能跨工具使用。代價：指令的具體語法在不同工具之間可能略有差異，這就是下一節的內容。

各工具的斜線指令語法 ​

意圖在所有地方都相同。拼寫方式遵循您的工具所載入的檔案。

您的工具的指令檔案您如何輸入範例工具
.../commands/opsx/<id>.*/opsx:proposeClaude Code, Gemini CLI, Crush
.../opsx-<id>.*/opsx-proposeCursor, GitHub Copilot (IDE), Devin Desktop, Trae, Oh My Pi
.amazonq/prompts/opsx-<id>.md@opsx-proposeAmazon Q Developer
無 — 僅限技能/openspec-proposeCodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent, 共用 .agents
無 — Kimi Code/skill:openspec-proposeKimi Code
無 — Codex CLI$openspec-proposeCodex

Devin 是唯一跨兩行的工具。Devin Desktop 讀取 .devin/workflows/，所以 /opsx-propose 在那裡可以運作；Devin Local 則不行，所以在該代理上使用 /openspec-propose 技能。OpenSpec 寫入 .devin/skills/ 的技能在兩者上都能運作，這就是為什麼它們透過技能名稱互相引用。

每個工具都列在 How To Invoke 中 — 該表格是權威來源。有兩行根本不是斜線指令：Amazon Q 將其檔案載入到使用 @ 呼叫的提示庫中，而最後三行使用技能名稱，這不是指令 ID（/opsx:apply 是 openspec-apply-change 技能）。

如果拿不定主意，請閱讀 openspec init 輸出的「Getting started」行：它已經使用了您的工具所註冊的格式。輸入斜線並觀察自動補全也有效，對於確實顯示斜線指令的工具而言。

指令如何到位：技能與指令 ​

當您執行 openspec init（或 openspec update）時，OpenSpec 會將小檔案寫入您的專案，讓您的 AI 工具能找到工作流程。根據您的工具和設定，這些是技能、指令，或兩者兼有。

  • 技能存放在 .claude/skills/openspec-*/SKILL.md 等位置。它們是正在興起的跨工具標準：一個您的助手會自動偵測的指示資料夾。
  • 指令存放在 .cursor/commands/opsx-<id>.md 或 .claude/commands/opsx/<id>.md 等位置 — 佈局由工具決定，它決定您如何輸入指令。它們是較舊的逐工具斜線指令檔案。Codex 不會生成指令檔案；請使用 .agents/skills/openspec-*。

您不需要在意您的工具使用哪一種。您只需輸入斜線指令，它就能運作。但知道這些檔案的存在在出問題時很有幫助：如果您的指令消失了，通常意味著這些檔案遺失或過期，而 openspec update 會重新生成它們。

請參閱 Supported Tools 了解每個工具的具體路徑，以及 Migration Guide 了解技能如何取代較舊的僅指令方式。

確認已安裝 ​

快速檢查，從最快的開始：

  1. 在您的 AI 聊天中輸入斜線。 開始輸入 /opsx 並觀察自動補全建議。如果它們出現，您就設定好了。在僅限技能的工具上（Codex、Kimi Code、CodeArts、ForgeCode、Hermes、Mistral Vibe、Zed Agent，或共用的 .agents 目標），即使安裝正常，/opsx 也永遠不會完成 — 請改用上方表格中的技能名稱。
  2. 尋找檔案。 對於 Claude Code，檢查 .claude/skills/ 是否包含 openspec-* 資料夾。其他工具使用它們自己的目錄（Supported Tools 有列出）。
  3. 重新執行設定。 從您的專案根目錄執行 openspec update。這會為您設定的工具重新生成技能和指令檔案。
  4. 重新啟動您的助手。 許多工具在啟動時掃描技能和指令，所以重新開啟視窗可能就是缺少的步驟。

我到底有哪些指令？ ​

預設情況下，OpenSpec 安裝核心斜線指令集：

  • /opsx:explore：在承諾變更之前與 AI 一起思考一個想法（不確定時是很好的第一步）
  • /opsx:propose：建立變更並一步草擬所有規劃產物
  • /opsx:apply：透過處理任務清單來建置變更
  • /opsx:update：修訂變更的規劃產物並保持它們一致
  • /opsx:sync：將變更的規格更新合併到您的主要規格中（通常自動完成）
  • /opsx:archive：完成變更並歸檔

一個好的預設節奏：在弄清楚要做什麼時使用 explore，然後 propose、apply、archive。Explore First 指南解釋了為什麼這個開頭步驟值得。

還有一個擴展集，供想要更精細控制的人使用（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard）。您用 openspec config profile 開啟它，然後用 openspec update 套用。

對這些完全陌生？/opsx:onboard（在擴展集中）會引導您在自己的程式碼庫上完成一個完整的變更，逐步解說每個步驟。它是最友善的入門方式。

每個指令的詳細說明，請參閱 Commands。何時使用哪個，請參閱 Workflows。

一次乾淨的首次執行 ​

綜合起來，以下是完整序列，每個步驟都標註了發生地點。

text
TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project
TERMINAL   $ openspec init
              （將斜線指令安裝到您的 AI 工具中）

AI CHAT      /opsx:explore
              （選填：先與 AI 一起思考這個想法）

AI CHAT      /opsx:propose add-dark-mode
              （AI 草擬提案、規格、設計、任務）

AI CHAT      /opsx:apply
              （AI 建置它，逐一勾選任務）

AI CHAT      /opsx:archive
              （變更已合併到您的規格中並歸檔）

兩個終端機步驟來設定。然後您就活在聊天中。這就是節奏。

相關資源 ​