基礎觀念

什麼是 Spec-Driven Development?

用白話解釋 spec-driven development 與 OpenSpec 的關係

一句話說清楚

規格驅動開發 (Spec-Driven Development) 是一種「先寫清楚再開工」的工作方式:在動手寫程式碼之前,先把要做的事情寫成一份可以被檢視、被修改、被驗收的規格 (Spec),然後才開始實作。

你可能會想:「我平常也會寫需求文件,這有什麼不同?」差別在於——在 spec-driven development 裡,規格不是寫完就丟一旁的附件,而是整套工作流程的中心。它跟程式碼住在同一個 repo,跟著變更一起演進,而且在每一個步驟都被當成「對的事實」來讀。

為什麼 AI 時代需要它?

當你跟 AI 助手(像是 Claude、Cursor、Copilot)一起寫程式,最常見的痛點是:

AI 不知道你的專案背景——它只看到你貼的幾行程式碼。
AI 給的建議常常「對但不貼合」——語法 OK,但跟你現有架構不一致。
改 A 壞 B——AI 幫你改了一個地方,結果另一個地方莫名壞掉。

這些問題的根源是:你跟 AI 之間沒有共用的事實。你腦袋裡有「為什麼這樣設計」,AI 沒有。文件散落各處(可能過時),AI 也不會主動去找。

Spec-driven development 透過把規格變成 repo 的一等公民,讓 AI 跟人都能讀到同一份脈絡。AI 不再憑空想像,而是依照現有的規格來產生變更。這就是 OpenSpec 想解決的核心問題。

OpenSpec 怎麼實作這個理念?

OpenSpec 是一套輕量的規格管理工具,圍繞著兩個關鍵資料夾運作:

your-project/
├── openspec/
│   ├── specs/        ← 已歸檔的「現況規格」(描述系統現在應該怎樣)
│   └── changes/      ← 進行中的「變更」(proposal / tasks / 暫存 spec)
├── src/
└── ...

規格 (Spec):放在 openspec/specs/,描述系統「現在」的行為,使用 SHALL / SHOULD / MAY 的需求語法,每條都帶驗收條件。
變更 (Change):放在 openspec/changes/<change-id>/,描述「未來要怎麼改」。一次變更是一個資料夾,裡面有 proposal.md(為什麼改)、tasks.md(怎麼做)、以及修改後的 spec delta。

「先同意再建構」的哲學

Spec-driven development 的核心精神是 agree before you build(先同意,再蓋)。在 OpenSpec 的工作流裡,這個精神落實成四個步驟:

提案 (Propose)——把要改的事情寫成 proposal.md,說明「為什麼改、改什麼、不改什麼」。
審查 (Review)——團隊(也包含 AI)對照現有規格,確認沒有衝突、沒有遺漏。
實作 (Apply)——依照 tasks.md 拆出的小任務,一步步改程式碼,同時更新對應的 spec。
歸檔 (Archive)——變更完成後,把這次改動併入主規格,openspec/changes/ 裡的暫存資料夾就功成身退。

這四步聽起來比「直接動手寫」多了一些工,但換來的好處是:

方向錯了提早發現——proposal 階段改文字比寫完程式碼再改便宜一百倍。
每一步都有紀錄——六個月後想當初為什麼這樣設計,翻 proposal.md 就好。
AI 協作更順——AI 讀得到 proposal、讀得到 tasks,它給的建議會更貼近你的意圖。

OpenSpec 的「OPSX」工作流

OpenSpec v1.6.0 提供 12 個 /opsx:* 指令,分別對應到上面四個步驟的細部操作。剛開始你只需要記得三個:

/opsx:propose — 幫你把模糊的想法展開成完整 proposal + spec delta + tasks。
/opsx:apply — 依照 tasks.md 一個一個小任務實作,改程式碼同時更新 spec。
/opsx:archive — 變更完成後,把這次的 spec delta 合併到主規格,資料夾歸檔。

這三個指令就能跑完一次「新增功能」或「修 bug」的完整循環。其他指令(/opsx:explore、/opsx:ff、/opsx:verify、/opsx:sync⋯⋯)是針對不同場景的進階工具,後面的章節會逐一介紹。

跟傳統開發流程的差別

項目	傳統流程	Spec-Driven Development
需求在哪裡	票券系統、Notion、聊天記錄	同一個 repo 的 `openspec/specs/`
為什麼這樣設計	「問當初的人」	翻 `proposal.md`
改了什麼	看 commit log 自己推敲	看對應 change 的 diff
跟 AI 溝通	把規格用訊息貼給 AI	AI 直接讀 repo 裡的規格
規格過時	經常	改程式碼時同步更新

小結

Spec-driven development 不是什麼新發明,它就是把「寫文件」這件事從「可選的習慣」升級成「流程的一部分」。OpenSpec 把這個流程具象化成 12 個指令跟兩個資料夾,讓你可以用很低的成本開始嘗試。

下一章 [OpenSpec 核心觀念] 會帶你認識更多專有名詞(spec delta、capability、scenario)跟最重要的指令分類。準備好就往下走吧!