指令詳解

/opsx:apply 指令詳解

如何使用 /opsx:apply 逐步實作任務並安全修改程式碼

指令用途

/opsx:apply 是規格驅動開發中唯一允許修改程式碼的實作指令。它是 AI 助手的實作引擎，也是將規格與設計轉化為真實系統行為的關鍵步驟。

當你執行 /opsx:apply 時，AI 助手會轉化為「實作者」的角色。它會嚴格遵循你在規劃階段產出的任務清單 (Tasks)，以最小且聚焦的改動原則，一步步修改代碼，並在每完成一個子任務時，立刻在 tasks.md 中將其打勾。

運作流程

  1. 鎖定計畫與 Schema：推斷或選擇目標變更計畫，並讀取其工作流架構 (Schema)。
  2. 閱讀背景脈絡：根據 instructions 指引，強制讀取所有關聯背景檔案（如 proposal.md, design.md, specs/ 與 tasks.md），以確保理解設計意圖，避免寫出與架構衝突的程式碼。
  3. 進入實作迴圈 (Implementation Loop)：
    • 找出下一個待辦任務（- [ ]）。
    • 修改對應的程式碼檔案。
    • 更新任務狀態為 - [x]。
    • 繼續下一個任務，直到任務全部完成。
  4. 暫停條件：如果遇到程式碼衝突、語意不清、設計需要修改，或是遇到了 🔴 人工檢查點，AI 會立刻暫停，保留進度並等待人類開發者指示。

實戰對話範例

以下是三個不同情境下的對話範例：

範例一：循序實作任務

  • You: 
    /opsx:apply
  • AI:

    Implementing: add-logout-feature (schema: spec-driven)

    正在處理任務 1/3：建立 src/components/LogoutButton.astro 元件。 [已建立該元件，並設定點擊時發送 POST 請求至 /api/logout] ✓ 任務已完成。已更新 tasks.md 中的勾選狀態。

    正在處理任務 2/3：於 Navbar 中引入此按鈕。 [已修改 src/components/Navbar.astro 檔案] ✓ 任務已完成。

    進度：2/3 任務已完成。下一個任務為「編寫單元測試」，是否繼續？

範例二：遇到設計瑕疵時主動暫停

  • You: 
    /opsx:apply
  • AI:

    Implementation Base: add-order-shipment-status

    正在處理任務 1/4：修改資料庫 Orders 資料表。

    ⚠️ 在實作過程中發現衝突： 我們的設計方案 design.md 規劃在 DB 欄位使用 shipment_status字串，但是目前專案中已存在一個現有的 OrderStatus 狀態列舉，兩者邏輯有所重疊。

    Implementation Paused

    選項：

    1. 更新規格與設計：將 shipment_status 合併至現有的 OrderStatus 列舉中。
    2. 堅持原設計：在資料庫建立新欄位，但需處理兩個狀態欄位的同步邏輯。

    請告訴我您想採用哪一個方案？

範例三：所有任務實作完成

  • You: 
    /opsx:apply
  • AI:

    Implementation Complete

    Change: add-logout-feature Progress: 3/3 tasks complete ✓

    本次會話完成之項目

    • 建立登出按鈕元件。
    • Navbar 整合。
    • 撰寫並通過 /api/logout 的整合測試。

    所有實作任務均已完成！請執行以下指令將變更歸檔並合併至主規格：

    /opsx:archive