指令詳解

/opsx:onboard 指令詳解

如何使用 /opsx:onboard 引導團隊快速上手完整規格驅動開發循環

指令用途

/opsx:onboard 是專為新手或初次導入 OpenSpec 專案的團隊所設計的教學指引指令。它的目標是透過引導式（Narrated）的工作流，帶領你手把手地在「真實程式碼庫」中完成一次完整的規格驅動開發循環。

執行此指令時，AI 不會直接幫你完成所有工作，而是會扮演「導師」的角色，為你掃描專案以尋找合適的 starter tasks（入門任務），並一步步解說各個階段的意義，讓你透過實作真正理解 OpenSpec 的工作流。

運作流程

  1. 環境預檢 (Preflight)：檢查專案本地是否已安裝 OpenSpec CLI 工具。若未安裝，會提示先進行安裝。
  2. 掃描程式碼庫尋找切入點：
    • 搜尋程式碼中的 TODO、FIXME 等註解。
    • 檢查是否有捕獲異常但未處理的 catch 區塊（Swallowed Errors）。
    • 找出沒有對應測試檔案的函數。
    • 檢查 TypeScript 檔案中是否濫用了 any 型別。
  3. 推薦任務清單：向使用者展示 3-4 個極小規模（約 1-2 個檔案，20 行代碼內）、非常適合用來練習 OpenSpec 的真實任務。
  4. 引導完整生命週期：
    • 使用者選擇任務後，AI 帶領建立變更計畫。
    • 指導並解釋如何生成 Proposal、Specs 規格書、Design 設計方案 與 Tasks 任務清單。
    • 帶領使用者一步步修改代碼，在 tasks.md 中打勾，最終執行驗證與歸檔。

實戰對話範例

範例一：掃描專案並給予任務推薦

  • You: 
    /opsx:onboard
  • AI:

    歡迎來到 OpenSpec 新手村！

    我會帶您在您的實體程式碼庫中，手把手完成一次規格驅動開發流程。

    正在為您掃描 codebase 尋找合適的入門任務⋯

    📋 入門任務推薦：

    1. 修復 Swallowed Error

    • 位置：src/utils/fetchData.ts:24
    • 說明：catch 區塊目前為空，應加上 console.error 或錯誤回報。
    • 難度：★☆☆ (適合初學者)

    2. 移除 any 濫用

    • 位置：src/components/UserAvatar.tsx:12
    • 說明：將 props 的類型定義由 any 改為具體 Interface。
    • 難度：★☆☆

    3. 自訂任務

    • 請告訴我您想手動嘗試哪一個修改？

    請問您想要從哪一個任務開始練習？

範例二：引導建立第一個 Proposal

  • You: 
    我選 1，修復 Swallowed Error
  • AI:

    太棒了！我們就來修復 fetchData.ts 中的錯誤吞噬問題。

    第一步：建立變更計畫 (Change) 我已自動為您建立了名為 fix-fetch-swallowed-error 的計畫。

    第二步：理解與生成提案 (Proposal) 在寫 code 之前，我們要先定義「為什麼改」。我已為您起草了 proposal.md。

    • 我們在其中定義了：若 API 請求失敗，SHALL 輸出錯誤日誌。

    請幫我打開該檔案，檢視內容是否符合您的想法？確認後請輸入「確認」，我將帶您進入下一個步驟：建立 tasks.md 實作地圖。

範例三：帶領實作與歸檔

  • You: 
    任務實作好了，測試也跑過了。
  • AI:

    非常棒！您已經完成了程式碼的修改。

    目前 tasks.md 中的所有實作任務都已經勾選為完成。

    最後一步：歸檔與同步 (Archive & Sync) 我們現在需要執行歸檔，這會自動把剛才在計畫中寫的「錯誤處理規格」合併到系統的 openspec/specs/ 中，並清理掉臨時資料夾。

    請執行以下指令來完成您的第一個 OpenSpec 循環：

    /opsx:archive

    恭喜您完成了 Onboarding 學習！