指令詳解

/opsx:propose 指令詳解

如何使用 /opsx:propose 一鍵建立變更計畫並生成所有規劃產物

指令用途

/opsx:propose 是啟動全新開發工作時最常使用的指令。它的作用是將一個模糊的開發想法（例如「修復登入閃退」或「新增商品評論功能」），在一個步驟中展開成結構化的變更計畫 (Change) 資料夾，並自動規劃與生成所有必要的規格與實作任務檔案。

此指令會引導 AI 助手在 openspec/changes/<change-name>/ 目錄下建立以下三個核心檔案：

  1. proposal.md (提案)：描述為什麼要改（Why）、改動內容（What）與不受影響範圍。
  2. design.md (設計方案)：選填，描述技術實現方案與架構設計。
  3. tasks.md (任務清單)：拆解出具體、可測試的實作步驟。

運作流程

  1. 解析輸入：指令後方的參數可以是一個簡單的描述（例如 /opsx:propose "新增購物車按鈕"）或一個已經命名好的 Change 代號。若未提供參數，AI 會主動詢問。
  2. 建立目錄：執行 openspec new change "<name>" 建立變更計畫資料夾。
  3. 分析狀態：透過 openspec status 取得依賴關係，以確保文件以正確的順序生成。
  4. 生成產物：AI 依序調用指令生成並寫入 proposal.md、design.md 與 tasks.md，並為你生成本次變更專屬的規格增量（Spec Delta）。
  5. 提示實作：生成完畢後，提示開發者審查這些文件，並可執行 /opsx:apply 進入實作。

實戰對話範例

以下是三個不同開發情境下的對話範例，展示 /opsx:propose 如何運作：

範例一：前端 UI 需求（新增深色模式）

  • You: 
    /opsx:propose "為教學網站加上深色模式切換按鈕"
  • AI:

    好的，我已為您建立變更計畫 add-dark-mode：

    • 建立 proposal.md: 規劃在右上角新增 Sun/Moon 圖示按鈕，儲存設定至 localStorage。
    • 建立 design.md: 採用 Tailwind CSS 的 dark 類別 (Class) 與 CSS 變數實作。
    • 建立 tasks.md: 拆解出元件製作、切換邏輯與樣式套用等 4 個步驟。

    所有規劃檔案已生成完畢！請執行 /opsx:apply 開始實作。

範例二：API 修改（新增訂單運送狀態欄位）

  • You: 
    /opsx:propose "在訂單 API 增加 shipment_status 欄位"
  • AI:

    好的，已建立變更計畫 add-order-shipment-status：

    • 建立 proposal.md: 修改 GET /api/orders 回傳格式，加入 shipment_status (枚舉值：processing, shipped, delivered)。
    • 建立 specs/order-api/spec.md: 更新 API 規格書，新增一個關於回傳欄位與格式的驗收情境 (Scenario)。
    • 建立 tasks.md: 包含修改資料庫 Model、API Serializer 及更新單元測試的任務。

    計畫已建立！確認無誤後請使用 /opsx:apply 執行修改。

範例三：資料庫優化（為訂單建立時間加上索引）

  • You: 
    /opsx:propose "為 orders 資料表的 created_at 欄位加上 index 以加速查詢"
  • AI:

    好的，已建立變更計畫 add-orders-created-at-index：

    • 建立 proposal.md: 解決訂單分頁查詢緩慢的問題。
    • 建立 design.md: 規劃遷移 (Migration) 腳本，使用並行建立索引 (CREATE INDEX CONCURRENTLY) 避免鎖表。
    • 建立 tasks.md: 任務包含產生 DB Migration 檔案、在 Staging 環境跑 Migration 並進行效能比對。

    規劃檔案已備妥，請執行 /opsx:apply 開始執行。