Featured image of post 在OpenCode中嘗試OpenSpec：規約驅動開發實踐分享
AI

在OpenCode中嘗試OpenSpec：規約驅動開發實踐分享

OpenCode環境下使用OpenSpec的體驗分享。探討規約驅動開發如何銜接AI編程助手與結構化開發工作流，以及我為什麼選擇OpenSpec而非Spec Kit。

引言：在OpenCode中使用OpenSpec

編程工作空間

最近我在OpenCode環境中嘗試使用OpenSpec，想分享這段體驗。不熟悉OpenSpec的朋友，簡單介紹一下：它是一個規約驅動開發（SDD）框架，為AI輔助編程工作流提供結構化支援。它現在支援與OpenCode整合，正好契合我的開發環境。

這篇文章裡，我會聊聊我對規約驅動開發的理解、它如何與vibe coding結合，以及為什麼我最終選擇了OpenSpec而非Spec Kit。

https://openspec.dev/

什麼是規約驅動開發？

規劃與文件

規約驅動開發（SDD） 是一種在寫程式碼之前先定義清晰規約的方法。不是直接跳到實作階段，而是先明確你要做什麼、為什麼做、以及它應該如何運作。就像蓋房子前先畫好詳細的設計圖。

核心工作流

OpenSpec遵循一個簡潔的三階段流程：

  1. Propose（提議） — 描述你的想法，AI生成提案、規約、設計文件和任務分解
  2. Apply（應用） — AI按照任務清單一步步實作變更
  3. Archive（歸檔） — 完成的變更被移動到歸檔目錄，保留清晰的記錄

主要優勢

  • 實作前對齊：在寫程式碼前，你和AI就方案達成一致
  • 持續上下文：規約文件存放在程式碼庫的openspec/目錄下
  • 可追蹤進度：任務以清單形式組織，方便監控和審查
  • 稽核軌跡：每次變更都有文件記錄

與Vibe Coding的結合

如果你喜歡vibe coding（那種憑直覺快速反覆的流動狀態開發方式），可能會擔心SDD會不會太死板。從我的經驗來看，它們其實相輔相成。Vibe coding適合探索和快速原型，SDD則在實作複雜功能或維護長期專案時發揮價值。先用vibe coding探索想法，準備建構可持續的成品時再切換到SDD。

更換oh-my-opencode的模型

kimi-k2.5

岔開話題一下：如果你看過我之前的發文，應該知道我在優化oh-my-opencode的模型配置。最近我又做了一個調整 —— 把主模型換成了Kimi K2.5。

有趣的是，這正好和最近的一則產業新聞呼應：Cursor最近承認他們的新Composer 2模型是基於Kimi K2.5作為訓練基座建構的。雖然Cursor在此基礎上做了繼續預訓練和強化學習，但底座是Kimi K2.5。這印證了我的選擇 —— 如果Cursor都押注Kimi做他們的編程助手，那我的配置裡也該考慮它。

OpenSpec與Spec Kit的對比

在選定OpenSpec之前，我也評估了GitHub的Spec Kit。對比結果如下：

維度 OpenSpec Spec Kit
方式 反覆式，提議優先 全面但重量級
最適合 既有專案、既有程式碼庫 全新專案、新功能
工作流 靈活階段（提議→應用→歸檔） 嚴格的階段關卡
配置 輕量（npm install） 需要Python環境
文件 Markdown格式，簡潔 大量Markdown模板
變更追蹤 內建（ADDED/MODIFIED/REMOVED） 需手動協調
工具支援 20+ 代理/IDE 8+ 支援的代理

關鍵差異

Spec Kit非常適合大型新功能開發，前期規劃的投入能透過減少重工獲得回報。它提供全面的模板和嚴格的階段關卡確保完整性。但這種剛性在小任務或維護既有程式碼庫時可能顯得過重。

OpenSpec則是為既有專案設計的。它使用變更標記（ADDED/MODIFIED/REMOVED）追蹤相對於既有功能的改動，非常適合反覆改進。工作流更靈活，可以隨時更新任何文件，沒有嚴格的階段關卡。

我為什麼選擇OpenSpec

試用兩者後，我因為幾個原因選擇了OpenSpec：

1. 維護既有專案

我的工作大多是維護既有專案，而非從零建構。OpenSpec的變更追蹤方式（標記為ADDED、MODIFIED或REMOVED）非常契合這種工作流。

2. 團隊協作考量

在團隊環境中，不是所有人都會用OpenSpec。OpenSpec的靈活性意味著即使團隊成員不用這個工具，也能理解和審查變更 —— 規約就是倉庫裡的Markdown檔案而已。

3. 簡潔性

OpenSpec更輕量、更易上手。不需要配置Python環境，也不需要研究複雜的模板。簡單的npm install -g @fission-ai/openspec就搞定。

4. 個人開發工作流

對個人專案和小任務，OpenSpec恰到好處。既提供了足夠的結構保持條理，又不會顯得官僚。

OpenSpec使用方法和小技巧

開始使用 

1
2
3
4
5
6

# 全域安裝OpenSpec
npm install -g @fission-ai/openspec@latest

# 在專案目錄初始化
cd your-project
openspec init

這會建立一個openspec/目錄，包含：

  • AGENTS.md — 給AI代理的指示
  • project.md — 全域專案上下文
  • specs/ — 目前系統規約
  • changes/ — 活躍的變更提案

基本工作流

proposal.md、design.md、tasks.md

  1. 建立提案：

    1

    /opsx:propose add-user-authentication

    AI會生成：proposal.md、design.md、tasks.md和變更規約

  2. 審查和優化：檢查生成的檔案，按需調整

  3. 應用變更：

    1

    /opsx:apply

    AI按任務清單逐項實作

  4. 完成後歸檔：

    1

    /opsx:archive

    完成的變更移到openspec/changes/archive/

使用小貼士

  • 從小做起：不要試圖一次性規約整個專案，先從一個功能或bug修復開始
  • 應用前審查：提案階段是抓住誤解的最後機會，趁程式碼還沒寫
  • 版本控制規約檔案：提交openspec/目錄，讓整個團隊受益
  • 既有專案用/opsx:onboard：這個指令掃描程式碼庫生成初始規約

總結

在OpenCode中使用OpenSpec幾週後，我確信規約驅動開發在現代AI輔助工作流中有一席之地。它不會取代vibe coding那種創造性、探索性的本質，但會在需要時增加一層有價值的結構。

OpenSpec的輕量方式和OpenCode的代理架構天然契合。無論你是維護既有程式碼、團隊協作，還是只是想更有意識地進行開發流程，我都建議試試。

如果你已經在用oh-my-opencode，整合是無縫的 —— 在專案中初始化OpenSpec，然後就開始使用斜線指令。對我的模型配置歷程感興趣的朋友，可以看看我之前關於oh-my-opencode模型選擇的文章。

你有沒有試過用OpenSpec或Spec Kit做規約驅動開發？歡迎在評論區分享你的體驗。