小狐狸事務所: Gemini CLI 學習筆記 : OpenSpec 初體驗 (二)

2026年4月25日星期六

Gemini CLI 學習筆記 : OpenSpec 初體驗 (二)

白天完成初次迭代後, 傍晚快馬加鞭進行第二次迭代.

本系列全部測試文章參考 :

前一篇的初次迭代由於功能較簡單, 我們使用了 /opsx:ff 快轉指令一鍵生成模式, 快速地完成了從規劃到程式碼生成與測試驗證的工作流. 本篇將在初次碟待的基礎上為基本的四則運算計算器添加次方與根號功能.

此二次迭代將改用逐步推進模式, 舊版 OpenSec 原本的的工作流需要依序執行下列指令 :

/opsx:new <iteration_name> (建立迭代之專屬的工作區)
/opsx:propose <requirements> (依需求起草提案書)
/opsx:continue (完成規格定義書 spec.md)
/opsx:continue (完成架構設計書 design.md)
/opsx:continue (完成任務清單 tasks.md)
/opsx:apply (依照 tasks.md 中的任務清單逐一實作功能)
/opsx:verify (驗證程式碼與規格完整性, 正確性, 一致性)
/opsx:archive (迭代完成歸檔)

執行 /opsx:propose 後, AI 只會生成第一份文件 proposal.md (提案書) 並把控制權交還給我們來審查功能描述是否與需求符合. 審查通過後就可執行三個連續的 /opsx:continue 指令, 一次只產出一份文件, 審查通過後再執行下一個 continue 指令.

第一個 /opsx:continue 指令, 它會生成規格定義書 spec.md, 注意, 這個檔案可能不只一個, 因為在模組化的軟體架構中, 功能會被解耦分拆在不同資料夾, 例如 :

openspec/changes/calc-power-root/specs/arithmetic-api/spec.md

openspec/changes/calc-power-root/specs/calculator-ui/spec.md

每一個功能都會有一個 spec.md 檔, 這些分散的規格定義書共同構成了這次迭代的完整規格.

第二個 /opsx:continue 指令會產生架構設計書 design.md, 主要是描述內部程式碼要怎麼實作, 審查重點在於有沒有過度設計 (Over-engineering), 例如明明 math 套件能做到的功能卻使用 numpy, 這實要將其改為 "使用 Python 內建 math 即可".

第三個 (也是最後一個) /opsx:continue 指令會生成任務清單 (施工單) tasks.md 檔, 這份文件是設計階段與實作階段之間的最後一座橋樑, 也是 AI 執行 /opsx:apply 時唯一的行動指南, 它只關注具體要做哪些動作. 審查時要檢查施工順序是否合理, 若無問題就可以下達 /opsx:apply 指令叫 AI 依照清單逐一實作程式碼, 完成驗證後即可歸檔.

但新版的 OpenSec 已經把三次 /opsx: continue 指令整合進 /opsx:propose 裡面了, 所以新版的工作流指令序列改為 :