用 OpenCode ＋ OpenSpec 落實省時省力的規格驅動開發 (SDD)

前言

最近實作 side Pproject —— PunchGo ⚡️，一個追求極致流暢的拍照打卡 app，過程中嘗試許多 AI 工具，在這將分享如何利用 opencode 與 openspec 進行規格驅動開發（SDD），從需求討論到程式碼實作與測試的過程。

基礎組合：opencode + openspec

opencode 是一個 CLI 介面的 AI 程式設計助手，而 openspec 則是一套基於 OpenAPI 的規格驅動開發工具。兩者搭配使用，可以從需求討論一路走到程式碼實作與測試。

工作流程

Step 1：開啟 opencode 並選擇 agent

在終端機輸入 opencode 啟動後，使用 /agents 指令選擇 plan native agent。這個 agent 擅長分析需求並產生執行計畫。

Step 2：提出功能需求

接著使用 /skills 載入 openspec 技能，然後用 /openspec-propose 提出想要的功能。例如：

/openspec-propose 在「我的打卡」tab 列出打卡紀錄，包含經緯度、文字描述和圖片

AI 會分析需求並產生一份嚴謹的計畫，包含架構設計、資料流與元件拆分。

Step 3：討論與調整

AI 產出計畫後，可以針對細節來回討論。例如調整 UI 設計、修改資料欄位或變更架構決策。這個階段可以充分發揮人機協作的好處。例如在這裡詢問我是否需要即時更新資料？我回答只要在使用者手動下拉更新即可，AI 就會自動調整計畫，並且更新待辦清單。

如果有疑問想問呢？

/openspec-explore 為什麼無法顯示建議的地點，只有地址呢？

AI 會根據之前的討論內容，分析出可能的原因，並且提出解決方案，之後即可改變實作計畫，讓它更符合實際需求。

Step 4：切換到 build agent

計畫確定後，使用 /agents 切換到 build native agent，然後執行 skills：

/openspec-apply-change

這個指令會把剛才討論的成果轉換為正式的設計文件、規格文件和待辦清單。

Step 5：自動實作

接著 build agent 就會開始依照待辦清單逐步實作。每完成一個項目，待辦清單會自動更新打勾，讓進度一目了然。

Step 6：撰寫測試

功能完成後，可以用 openspec 來產生測試，舉例來說剛才實作「我的打卡」功能之後，可以利用它的規格來產生測試計畫：

/openspec-propose my-punches-list-test 根據 my-punches-list 利用 vitest 實作 unit test

同樣會產生完整的測試計畫，經由討論確認後即可開始實作。測試涵蓋率高，且與規格保持一致。

Step 7：歸檔

工作全部完成後，執行 /openspec-archive-change 將相關文件歸檔，保持工作區乾淨整潔。

Agentic AI / Agent to Agent

除了手動下指令，如果在 local 定義了一份文件，或者想搭配工作流程自動讀取 Jira Ticket 的內容，可以進化為自動化 pipeline 模式，也就是說做成一個 skill 讓它自動讀取需求文件，解析後產生規格，最後實作出來。

運作流程如下：

1. 讀取與解析 (@ticket-reader)：pipeline 會自動呼叫 ticket-reader，去讀取並精準拆解 replace-geolocation-with-address.md 裡面的需求與驗收條件（Acceptance Criteria）。
2. 產生提案 (@change-proposer)：接著交給 change-proposer 依據解析出來的結構，自動在專案中生成嚴謹的 OpenSpec 規格提案與變更計畫。
3. 暫停等待審查 (pause for review)：規劃完成後，pipeline 會暫停，將主導權交還給開發者確認計畫是否正確。
4. 核准即實作 (implement on approval)：一旦得到允許，執行 agent 就會開始實作。

舉例來說，新需求為把經緯度換成人類可讀地址的需求，在這裡將準備好的需求單放到指定資料夾後，直接執行指令：

/ticket tickets/replace-geolocation-with-address.md

接著 pipeline 就會自動讀取需求，解析出結構化的規格，產生提案，最後等待審查。審查通過後就會開始實作。

總結

這個流程的核心優勢在於：

• 規格驅動：先討論規格再實作，避免思考不周、邊做邊改。
• 人機協作：AI 處理細節與重覆勞動，開發者專注在決策與設計。
• 文件同步：設計檔、規格檔、待辦清單與程式碼保持同步，減少溝通成本。
• 測試先行：規格確定後自動產生測試，品質更有保障，更有機會做到 TDD。