OpenSpec

常見問題解答 (FAQ) ​

快速回答大家最常提出的問題。如果您的問題屬於「系統出現故障」類型，疑難排解頁面會更適合您。如果您需要定義某個術語，請參閱詞彙表。

基礎知識 ​

用一句話來說，OpenSpec 是什麼？ ​

一個輕量級層級，讓開發者與 AI 程式碼助手在編寫任何程式碼之前，先以書面形式就「要建構什麼」達成共識。

我為什麼需要這個？ ​

因為即使 AI 助手錯了，它們依然表現得很有自信。當需求僅存在於聊天記錄中時，AI 會用猜測來填補空白，而你要等到程式碼已經生成後才發現問題。OpenSpec 將共識過程提前，此時修正錯誤的成本較低。完整論述請見核心概念一覽。

我必須對所有事情都使用它嗎？ ​

不需要。在需要達成共識的地方使用它，這通常適用於大多數非瑣碎的工作。對於只修正一個字元的錯字這類小任務，這些流程可能不值得，這沒關係。

我可以將其用於大型現有程式碼庫，還是只能用於新專案？ ​

現有程式碼庫才是主要應用場景。OpenSpec 優先支援棕地（brownfield）專案：你不需要一開始就文件化整個應用程式。你只需為每次變更所涉及的內容撰寫規格，隨著實際工作的進行，你的規格也會逐漸完善。我們有專門的指南：在現有專案中使用 OpenSpec。

它是否綁定特定的 AI 工具？ ​

不是。OpenSpec 可與 30 多種助手配合使用，包括 Claude Code、Cursor、Devin Desktop、GitHub Copilot、Gemini CLI、Codex 等。完整列表及各工具的詳細資訊請見支援的工具。

執行命令 ​

我在哪裡輸入 /opsx:propose？ ​

在你的 AI 助手的聊天視窗中，而不是終端機裡。這是最常見的混淆點，因此它有專屬頁面：命令如何運作。簡短版本：openspec ... 在終端機中執行，/opsx:... 在聊天中執行。

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

沒有單獨的模式需要啟動。像平常一樣打開你的 AI 助手，並在它的聊天視窗中輸入斜線命令。斜線命令就是你「進入」OpenSpec 的方式。（唯一真正具有互動性的終端機功能是 openspec view，這是一個用於瀏覽規格和變更的面板。）完整說明請見命令如何運作。

我輸入了一個斜線命令，但沒有任何反應。為什麼？ ​

最有可能的原因是你是在終端機而不是 AI 聊天中輸入的，或者你使用的拼寫工具無法識別，又或者尚未安裝這些命令。如果檔案遺失——或者你從未設定該工具——請執行 openspec init；openspec update 僅更新已存在的檔案。然後重新啟動你的助手，並使用「入門」下方列印的格式——請參閱如何呼叫。疑難排解提供了完整的檢查清單。

為什麼這個工具的語法是 /opsx:propose，而另一個是 /opsx-propose？ ​

每個 AI 工具呈現自訂命令的方式略有不同，OpenSpec 會根據你的工具載入其寫入的檔案的方式來拼寫它們。名為 opsx-propose.md 的命令檔案輸入為 /opsx-propose；歸類在 commands/opsx/ 下的檔案輸入為 /opsx:propose。採用技能而非命令的工具使用技能名稱——Codex 需要 $openspec-propose，Kimi Code 需要 /skill:openspec-propose。openspec init 的「入門」行已經為你選擇的工具列印了正確的格式；完整表格請見如何呼叫。

技能和命令有什麼區別？ ​

兩者都是 OpenSpec 寫入的檔案，以便你的助手可以執行工作流程。技能（.../skills/openspec-*/SKILL.md）是較新的跨工具標準；命令（.../commands/opsx-*）是較舊的每工具斜線檔案。你不需要選擇。你只需輸入斜線命令，OpenSpec 就會安裝你的工具所使用的任何一種。

工作流程 ​

如果我不確定要建構什麼，應該從哪裡開始？ ​

從 /opsx:explore 開始。它是一個無風險的思考夥伴，會讀取你的程式碼庫，列出選項，並將模糊的問題轉化為具體的計畫，而且所有這些都在任何變更或程式碼存在之前完成。它位於預設配置檔中，因此隨時可用。當計畫明確後，它會移交給 /opsx:propose。這是應養成的最佳習慣，因為它可以防止熱心的 AI 自信地建構錯誤的內容。請見先探索。

最簡單的可能流程是什麼？ ​

text
/opsx:explore (選填)   接著   /opsx:propose <你想要的内容>   接著   /opsx:apply   接著   /opsx:archive

透過 Explore 進行思考，透過 Propose 草擬計畫，透過 Apply 進行建構，透過 Archive 進行存檔。如果你已經清楚知道自己想要什麼，可以跳過 Explore。

/opsx:propose 和 /opsx:new 有什麼區別？ ​

/opsx:propose 是預設的一步式命令：它會建立變更並同時草擬所有規劃工件。/opsx:new 是擴充命令集的一部分，僅搭建空的變更框架，讓你使用 /opsx:continue（一次一個）或 /opsx:ff（一次性）來建立工件。除非你需要逐步控制，否則請使用 propose。請見命令。

什麼是 core（核心）和 expanded（擴充）配置檔？ ​

配置檔決定安裝哪些斜線命令。Core（預設）提供 propose、explore、apply、update、sync、archive。Expanded 集合增加了 new、continue、ff、verify、bulk-archive 和 onboard 以提供更精細的控制。使用 openspec config profile 切換，然後使用 openspec update 套用。

我需要執行 /opsx:sync 嗎？ ​

通常不需要。Sync 會將變更的差異規格合併到你的主規格中，而 /opsx:archive 會主動提出幫你執行此操作。僅在你希望在存檔之前合併規格時才手動執行 sync，例如在長期運行的變更上。請見命令。

一旦開始後，我該如何編輯提案、規格或任務？ ​

直接編輯檔案即可。每個工件都是位於 openspec/changes/<name>/ 中的純 Markdown，沒有鎖定的階段或特殊的編輯模式。你可以手動更改它，或要求你的 AI 進行修訂（例如「更新設計以使用佇列」），然後繼續進行。AI 始終基於當前檔案內容工作。完整指南：編輯與迭代變更。

在實施部分內容後，我可以回去更改計畫嗎？ ​

可以，隨時都可以。工作流程是流動的，因此審查和編輯不會成為你無法進行的階段。編輯工件，然後繼續進行。如果你希望進行結構化的檢查以確保程式碼仍符合計畫，請執行 /opsx:verify。請見編輯與迭代變更。

我手動編輯了程式碼。我該如何將其與規格協調一致？ ​

在存檔之前將它們恢復同步，因為存檔會使你的規格成為事實記錄。如果程式碼現在是正確的，請更新差異規格以匹配你交付的內容；如果規格是正確的，則繼續構建直到程式碼一致。/opsx:verify 會顯示不匹配之處。請見編輯與迭代變更。

我應該何時更新現有變更，何時開始新變更？ ​

如果是同一項工作的優化，請更新。如果是意圖根本改變或範圍膨脹成不同的工作，請重新開始。在工作流程中有決策流程圖和範例。

如果我的工作階段超出上下文限制，或在實施中途需求發生變化怎麼辦？ ​

這就是規格發揮作用的地方。由於計畫存在於檔案中（而不僅僅是聊天歷史中），你可以清除上下文，啟動新的 AI 工作階段，並通過 /opsx:apply 繼續；它會讀取工件並從第一個未勾選的任務恢復。如果需求發生變化，請編輯工件以匹配新現實並繼續。保持清晰的上下文窗口也能產生更好的結果；在實施前清除它。

我應該將 openspec/ 資料夾提交到 git 嗎？ ​

是的。你的規格、活躍變更和存檔都是專案歷史的一部分。像其他來源一樣提交它們。特別是存檔，它會成為記錄你的系統為何如此運作的重要憑證。

規格與變更 ​

規格和設計中分別包含什麼？ ​

規格描述可觀察的行為：系統做什麼、它的輸入、輸出和錯誤條件。設計描述你將如何構建它：技術方法、架構決策、檔案變更。如果實現方式可以改變而不影響外部可見行為，則它屬於設計，而非規格。概念深入探討了這一點。

什麼是差異規格（delta spec）？ ​

一種僅描述變更內容的規格，使用 ADDED、MODIFIED 和 REMOVED 區塊，而不是重述整個規格。這是 OpenSpec 乾淨地處理現有系統編輯的方式。請見概念。

已存檔的變更存放在哪裡？ ​

存放在 openspec/changes/archive/YYYY-MM-DD-<name>/，保留所有變更工件。該變更是從你的活躍列表中移出的。明確宣告 retire_capabilities: true 的變更是可以在移除該能力的最後一項需求時刪除主能力規格的。

配置與自定義 ​

我該如何讓 AI 知道我的技術堆疊？ ​

將其放在 openspec/config.yaml 下的 context: 中。這段文字會被注入到每個規劃請求中，因此 AI 始終知道你的堆疊和慣例。請見自定義。

我可以生成非英文語言的規格嗎？ ​

可以。在你的配置的 context: 中添加語言指令。多語言提供了幾種語言的複製貼上片段。

我可以更改工作流程本身嗎？ ​

可以，使用自定義架構。架構定義了哪些工件存在以及它們如何相互依賴。使用 openspec schema fork spec-driven my-workflow 分叉預設值，然後編輯它。請見自定義。

模型、隱私和升級 ​

我應該使用哪個 AI 模型？ ​

OpenSpec 在高推理能力的模型上效果最好。README 推薦使用如 Codex 5.5 和 Opus 4.7 等模型進行規劃和實施。同時保持上下文窗口清潔：在實施前清除它以獲得最佳結果。

OpenSpec 會收集數據嗎？ ​

它收集匿名使用統計數據：僅限命令名稱和版本。不包含參數、路徑、內容或個人數據，並且在 CI 中自動關閉。可以使用 export OPENSPEC_TELEMETRY=0 或 export DO_NOT_TRACK=1 選擇退出。

我該如何升級？ ​

兩個步驟。升級套件（npm install -g @fission-ai/openspec@latest），然後在每個專案內運行 openspec update 以刷新生成的技能和命令。

我該如何解除安裝 OpenSpec？ ​

沒有解除安裝命令，因為它只是一個全局套件加上專案中的檔案。移除套件（npm uninstall -g @fission-ai/openspec），並可選地刪除 openspec/ 目錄和生成的工具檔案。逐步說明，包括哪些可以安全保留，請見安裝：解除安裝。

獲取幫助 ​

我在哪裡提問或報告錯誤？ ​

這些文檔有誤或令人困惑。我該怎麼辦？ ​

告訴我們，或修復它。歡迎並重視文檔 PR。開啟 Issue 或發送拉取請求。