！ 本篇文章將會介紹 OpenSpec 與 spec-driven development，需求不再活在聊天記錄裡，而是變成 repo 的一等公民 :D

TL;DR: https://dev.benben.me/slides/s/ironman-23-openspec

本篇目標

讀完這篇你會學到：

• SDD（spec-driven development）的核心概念
• OpenSpec 的安裝與 /opsx 變更流程
• specs 即 source of truth 的工作方式

問題：需求活在 chat history 裡

Day 06 說過：九成的「AI 做錯」其實是「人沒講清楚」。但還有一個更陰險的版本——講清楚了，可是只講在對話裡：

• session 一關，需求就消失
• 換一個 agent / 一個工具，全部重講
• 三週後你自己也不記得當初為什麼這樣設計

Spec-driven development（SDD）的解法很樸素：在寫 code 之前，先把「要什麼」寫成 spec，跟 code 一起進 repo。

OpenSpec 是什麼？

OpenSpec（Fission-AI 出品，MIT 開源）是 AI coding assistant 的 SDD 框架，支援 30+ AI 工具——opencode、Claude Code、Cursor、Codex 都能用。官方哲學口訣：

→ fluid not rigid        流暢而非死板
→ iterative not waterfall 疊代而非瀑布
→ easy not complex       簡單而非複雜
→ built for brownfield   老專案也能用
→ scalable               個人專案到企業都行

特別注意 brownfield ——不是只有新專案才能導入，既有的爛攤子更需要的其實是規格，沒有 spec ？直上 OpenSpec 沒問題。

快速上手

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

init 會建出 openspec/ 目錄、裝好對應工具的 slash commands，並印出你的工具該用的指令拼法（不同工具的命令格式略異：/opsx:propose、/opsx-propose 等）。

核心流程：explore → propose → apply → archive

第一步：還不知道要什麼？先 explore

/opsx:explore

「我想要 dark mode 但不確定怎麼做才乾淨」——explore 是零承諾的思考夥伴：讀你的 code、權衡選項、一起把計畫聊成形。還沒到寫 spec，先想清楚。

第二步：propose——把想法變規格

/opsx:propose add-dark-mode

AI 建立 openspec/changes/add-dark-mode/：

openspec/changes/add-dark-mode/
├── proposal.md   # 為什麼做、改哪些面
├── specs/        # 需求與場景
├── design.md     # 技術方案
└── tasks.md      # 實作清單

spec 是純 markdown，沒有特殊語法要學：

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

重點：AI 寫 spec，你在任何 code 動工前 review。不滿意就改 spec——改一段 markdown 比改一堆 code 便宜太多。

第三步：apply——照著 tasks 實作

/opsx:apply

AI 按 tasks.md 逐項實作、勾進度。因為規格已對齊，實作階段幾乎不用來回猜。

第四步：archive——歸檔並更新主 spec

/opsx:archive

變更歸檔進 openspec/changes/archive/，主 spec 目錄同步更新——openspec/specs/ 永遠反映系統現在的真實樣貌。

specs 即 source of truth

這是 OpenSpec 的心臟：

未來任何 session、任何 agent、任何人，打開 openspec/specs/ 就知道系統「應該」長什麼樣。

• 新需求 = 先提變更（change），review 過才動 code
• 系統現況與 spec 不一致 = bug 或債，看得出來
• onboarding 新人（與新 agent）= 讀 spec，不是讀你的記憶

OpenSpec 自己就是用 OpenSpec 開發的——repo 裡的 specs 就是活教材。

與 opencode 的合作姿勢

兩者天作之合：OpenSpec 的 slash commands 裝進 opencode 後，/opsx:propose 就是 Day 13 的 custom commands；spec 流程的紀律配上 Day 11 的 agents（plan agent 走 explore/propose、build agent 走 apply），規格與執行各司其職。

跟同類工具的差異

• vs GitHub Spec Kit：Spec Kit 紮實但厚重（明確 phase gates、較多儀式）；OpenSpec 走輕量、隨時可改
• vs Kiro（AWS）：Kiro 綁自家 IDE 與模型；OpenSpec 用你手上任何工具
• vs 什麼都不做：需求漂移、AI 猜謎、重講百遍——你知道的

常見問題

Q：小專案也要 SDD？會不會太儀式？
A：官方設計就是「輕」。小改動可以跳過 explore 直接 propose，spec 一頁也行。判斷標準：這個改動「三週後還需要被理解嗎」？要，就值得一份 spec。

Q：spec 會跟 code 一起爛掉嗎？
A：會，如果沒紀律。OpenSpec 的 archive 步驟就是在防這個——每次變更都回寫主 spec。把「spec 更新」當成 PR 的一部分，跟測試一樣對待。

Q：聽說有「Stores」是什麼？
A：beta 功能——把 openspec/ 放在獨立的 planning repo，跨多 repo 的功能一份計畫共享，平台團隊管 spec、產品團隊唯讀引用。團隊級玩法，有興趣看官方 Stores 指南。

小結

• SDD 把需求從 chat history 升級成 repo 一等公民
• 流程四步：/opsx:explore → propose → apply → archive
• spec 是純 markdown，openspec/specs/ 永遠等於系統現況
• 30+ 工具通用，與 opencode 的 commands/agents 無縫接軌

明日預告

Day 24：open-slide——為 agent 而生的簡報框架，本系列的每一份簡報大綱就是它做的。

有任何疑問但沒有 iT 邦幫忙帳號，或是想匿名提問？
歡迎到 https://dev.benben.me/q/P3C5U6 提問或加油打氣，沒意外的話會在完賽之後一起回答 :D