雖然早就在 Threads 上看過 OpenSpec 的討論，但當時我只想先專心研究 Spec Kit（想把它徹底搞懂XD），也就沒有特別往下研究。一直到 2026 年 1 月底，我看到龍哥寫的〈OpenSpec 讓 SDD 變簡單的三個指令〉。文章把 OpenSpec 介紹得超級詳細！也讓我再次對這套工具產生興趣。
不久後，龍哥又分享了 Superpowers 搭配 OpenSpec 的作法。那時候 Superpowers 也剛好很紅，龍哥寫這篇文章時，它在 GitHub 已經接近 3 萬顆星。
真正吸引我的，是龍哥把 Superpowers 的 brainstorming Skill 也接進他的 OpenSpec workflow：先和 AI 一題一題把需求與可能的作法談清楚，再把討論結果接進 OpenSpec。這樣我可以先用固定的 brainstorming 流程把需求談清楚，再進入 OpenSpec，不用每次都先用一般對話討論完，再自己把結果帶回 SDD workflow。看到這套組合後，我就決定正式踏進 OpenSpec 的世界！
brainstorming是什麼？ 當時的 Skill 會先查看專案現況，再以一次一題的方式確認目的、限制與成功條件；接著提出 2～3 種作法並說明各自的取捨，最後把設計分成幾個段落逐段確認。整個過程會先把需求與設計聊清楚，再往實作走。
這一篇先不急著說第一次實驗的結果。我想先和【Day - 3】一樣，看看 OpenSpec 會在專案裡放進哪些檔案、一個 change 會產生什麼，以及這些內容怎麼一路接到實作。等把操作時看得到的流程與文件弄清楚後，下一篇再實際打開背後的設定，一層一層往裡面看。
這篇使用哪個版本？ 我實際開始使用時，OpenSpec 已經進入 1.0。接下來這幾篇介紹 OpenSpec 時，都以當時的 1.0 workflow 為主；新版差異再用引用區塊補充。
和 Spec Kit 一樣，OpenSpec 也有自己的 CLI。安裝完成後，可以在專案中執行 openspec init，再選擇要搭配的 AI Agent。以我當時使用的 Claude Code 來說，剛完成初始化時，和本文有關的資料夾大致如下：
這裡先統一一下名稱： 和前面介紹 Spec Kit 時一樣，後續會直接使用流程名稱。例如，
/opsx:new→ new、/opsx:continue→ continue，其他流程也是相同的用法。
左邊的 .claude/skills/ 放著 AI 在各階段會使用到的 Skills；右邊的 openspec/ 則先準備好專案設定、正式規格與 changes 的存放位置。這時候還沒有建立任何 change，所以圖中的 changes/ 底下也不會出現 <change-name>/、.openspec.yaml 或規劃文件。
進入流程圖之前，先把這篇會用到的幾個流程說清楚：
| 流程 | 這個流程在做什麼？ |
|---|---|
| explore（可選） | 想法還不清楚時，可以在建立 change 前先和 AI 討論需求與可能的作法。 |
| new | 建立一個新的 change，準備保存這次變更的 artifacts；它本身不會一次產出全部規劃文件。 |
| continue | 依照 artifacts 的相依關係，每次建立一份目前已經可以產生的 artifact，讓我們逐份查看與調整。 |
| ff | 依照 artifacts 的相依順序，一次建立到可以進入實作為止。 |
| apply | 讀取 tasks 開始修改 code，並更新每一項工作的完成狀態。 |
| verify（可選） | tasks 完成後，把實作與 change artifacts 放在一起核對，找出漏做、不一致或偏離設計的地方。 |
| sync（可選） | 把這次 change 對規格的修改合併回正式 specs，但不會結束這次 change。 |
| archive | 確認 artifacts 與 tasks 的狀態，詢問是否需要同步規格，再把完成的 change 移進 archive。 |
如果需求還沒談清楚，可以先用 explore 和 AI 繼續討論；方向確定後，再用 new 建立 change。
寫鐵人賽時才發現我漏看了 explore： 當時的 OpenSpec 其實已經有 explore，只是我使用時沒有深入研究。這次為了寫鐵人賽文章回頭查看，才發現它早就存在，只能說我當時真的漏看得很徹底XD。
change 建立後，可以重複執行 continue，逐份建立這次規劃需要的 artifacts。如果需求與技術作法已經談得很清楚，也可以直接用 ff（Fast Forward），一次準備好實作前需要的內容。因為前面已經經歷過 Spec Kit 一步一步的流程，所以我後來幾乎都直接使用 ff XD。但不論選擇哪一條路徑，最後都會接到 apply。
實作完成後，如果想在歸檔前先檢查實作有沒有對上這次的規格與設計，可以先使用 verify。它不是 archive 的強制條件，apply 完成後也不會自己接著執行，所以這是一條需要時才會走的檢查路徑。
另外，sync 可以先把這次 change 對規格的修改合併回正式 specs，但 change 仍然會留在進行中的目錄。這一步不一定要自己先執行，也可以直接進入 archive，archive 就會在歸檔前和我們確認是否需要同步規格。
圖中的箭頭，來自各個 Skills 完成後給出的下一步建議。例如，new 完成後會提醒我們使用 continue，規劃文件準備好後會提醒我們進入 apply，tasks 全部完成後則會提醒我們進入 archive。當這些提示串起來，就是圖中的這條 workflow。
這些都只是下一步建議，我們不一定要立刻照著往下走，還是可以依照當下的狀態選擇接下來要做什麼。OpenSpec 採用 action-based workflow，new、continue、apply 與 archive 都可以依照當下的狀態選擇；artifacts 之間的相依關係只負責判斷哪些內容已經可以建立，不是在規定下一步只能做什麼。至於這組關係怎麼表示，等打開 change 裡的內容後就會看到。
知道 new、continue 與 ff 分別在做什麼後，再回頭看 changes/ 裡的內容就比較清楚了。執行 new 後，OpenSpec 才會建立這次 change 的目錄，並先放入 .openspec.yaml；接著使用 continue 或 ff，proposal、specs、design 與 tasks 才會逐步出現：
把一個 change 最後會留下的內容放在一起看，大致如下：
| 檔案或目錄 | 這份內容在做什麼？ |
|---|---|
.openspec.yaml |
保存這個 change 的基本設定與建立資訊；完整內容留到下一篇再打開來看。 |
proposal.md |
說明為什麼要改、這次要改什麼，以及會影響哪些 capabilities。 |
specs/ |
依 capability 記錄這次準備新增、修改、移除或改名的規格內容。 |
design.md |
整理技術背景、目標、重要決策、替代方案，以及風險與取捨。 |
tasks.md |
根據前面的規格與設計，整理接下來可以執行與追蹤的工作。 |
capability 是什麼？ OpenSpec 會用 capability 表示一項系統能力，例如前面看過的登入與驗證功能，就可以整理成
authcapability。正式規格與這次 change 準備修改的內容，都會沿用這個名稱放進對應的specs/目錄；proposal 如果同時影響好幾項 capabilities，specs/也會依照這些名稱分開保存。
.openspec.yaml 保存的是 change 的基本資料，不是規劃內容本身；proposal、specs、design 與 tasks 才是這次 change 的 artifacts。
現在有什麼不同？ OpenSpec 1.0 當時如果想一次準備好實作前需要的 artifacts，會先用 new 建立 change，再透過 ff 產生後續文件。目前的 OpenSpec 已經可以直接使用 propose，一次建立 change 並準備好實作前需要的規劃文件。
這裡要注意！propose 是流程名稱，
proposal.md則是 change 裡的一份 artifact，只是這個流程產生的其中一份規劃文件。
這幾份 artifacts 裡，specs/ 還需要再多看一眼。因為專案根目錄與 change 裡面各有一個 specs/，要分清楚兩邊的差別，得先知道一份正式規格裡面會寫什麼。
沿用【Day - 6】的登入與驗證功能，我們先看看 auth 這份簡化的正式規格裡會寫些什麼：
# auth Specification
## Purpose
定義使用者登入、驗證與 session 相關的行為。
## Requirements
### Requirement: Session 過期處理
系統 SHALL 在 session 過期後拒絕受保護的請求。
#### Scenario: 使用過期 session 存取受保護頁面
- **WHEN** 使用者帶著已過期的 session 發出請求
- **THEN** 系統拒絕存取，並要求使用者重新登入
Purpose 先說明 auth 這項 capability 負責的範圍；Requirements 下面則可以放好幾條 requirement。每一條 requirement 代表系統必須提供的一項行為，並且有自己的名稱；底下的 scenarios 再把這項行為放進具體情境，寫清楚在什麼條件下應該看到什麼結果。
以上面的內容來說，「Session 過期處理」就是 requirement 名稱，下面的 scenario 則把可以驗證的條件與結果列出來。這個名稱也不只是方便閱讀，後續合併規格時，工具會用它找出正式 spec 裡對應的 requirement。
看懂 spec 裡面的結構後，再回頭看兩個 specs/ 目錄就比較清楚了。openspec/specs/<capability>/spec.md 保存系統目前的正式規格；openspec/changes/<change-name>/specs/<capability>/spec.md 放的則是 delta spec，只描述這次 change 準備怎麼調整其中的 requirements。
delta 在這裡是什麼意思？ OpenSpec 官方 Glossary 將 delta spec 說明為只描述這次 change 改了什麼，不需要重寫整份 spec。簡單來說，它就是「這次 change 和目前正式規格之間的差異」。
當時預設的 spec-driven workflow 會用四種操作整理這些差異：
| 操作 | 什麼時候使用？ | 合併回正式 spec 後會發生什麼？ |
|---|---|---|
ADDED |
這次要加入原本不存在的新 requirement | 把新 requirement 加進正式 spec。 |
MODIFIED |
既有 requirement 的行為需要調整 | 用修改後的完整內容，取代正式 spec 裡的同名 requirement。 |
REMOVED |
既有 requirement 已經不再需要 | 從正式 spec 移除同名 requirement。 |
RENAMED |
requirement 的行為不變，只需要調整名稱 | 把原本的名稱換成新名稱。 |
這裡最需要注意的是 MODIFIED。它不是只寫「逾時時間從 15 分鐘改成 30 分鐘」這一句差異，而是要把修改後的 requirement 完整放進來，原本仍然有效的 scenarios 也要一起保留。等到 sync 或 archive 時，這一整段才會取代正式 spec 裡的原始版本。
真正套用時，MODIFIED 與 REMOVED 會透過 requirement 名稱，到正式 spec 裡尋找同一條內容，所以要沿用既有名稱；RENAMED 則會明確寫出原名稱與新名稱。也就是說，delta spec 不只要寫清楚內容，還要先選對這次是在新增、修改、移除，還是單純改名。
所以，change 裡的 specs/ 不需要再複製一份完整的正式規格，只要留下這次變更用到的操作與內容。等到執行 sync 或 archive，OpenSpec 才會把這些差異合併回正式 specs。
不過，知道 specs/ 裡要寫什麼之後，一個 change 裡還有 proposal、design 與 tasks，而且這些 artifacts 也不是同時建立。接下來再看看它們之間有什麼先後關係。
前面介紹 continue 時提過，它每次只會建立一份目前已經可以產生的 artifact。OpenSpec 會根據 artifacts 之間的相依關係判斷先後順序，官方把這組關係稱為 DAG（Directed Acyclic Graph，有向無環圖）：
在這張圖裡，proposal 是起點，specs 與 design 都會參考它；tasks 則要等規格與設計準備好，才有足夠的內容可以往下建立。OpenSpec 會負責追蹤哪些 artifacts 已經完成、哪些已經可以建立，以及哪些還在等待相依的內容。
用 continue 逐份建立，或是一次把規劃文件準備好，產生的 proposal、specs 與 design 都可以再回頭修改。不過，修改其中一份後，其他 artifacts 要不要跟著更新，當時仍然要自己判斷。這個問題先記著，等實際遇到中途變更時再回來看。
到這裡，我們已經知道 continue 會依照相依關係決定下一份 artifact。可是，這組關係實際上寫在哪裡？change 又怎麼記得自己使用哪一套 workflow？AI 從哪裡拿到文件格式、專案背景與每個階段要遵守的規則？下一篇，我們就把這些設定與 Skills 打開來看，看看 OpenSpec 怎麼決定先建立哪份 artifact、準備文件需要的內容，再交給 AI 撰寫吧！
brainstorming Skill
openspec init
iThome鐵人賽
看影片追技術