基礎觀念

你的第一個 Change

完整走一遍 OpenSpec 變更計畫的生命週期：Propose、Apply、Archive

走過一次，就會記住

在完成了專案初始化後，接下來我們將實際走一遍 OpenSpec 規格驅動開發的完整生命週期。我們將以一個非常簡單的需求——「為網站新增深色模式 (Dark Mode)」為例，示範如何建立並完成你的第一個變更計畫 (Change)。

1. 建立計畫：opsx:propose

一切的起點都源於一個想法。首先，我們必須將這個模糊的想法轉化為結構化的提案。此時，我們可以使用 AI 助理指令：

/opsx:propose "新增網站深色模式切換按鈕"

這個指令會引導 AI 掃描專案，並在 openspec/changes/ 下自動生成一個代號為 add-dark-mode 的子資料夾，同時建立四個必備的規劃產物：

  1. proposal.md：寫明新增深色模式的 Why 與 What（例如在網頁右上角新增一個 toggle 按鈕）。
  2. specs/dark-mode/spec.md (規格增量)：定義深色模式的驗收場景（Scenario），例如「當使用者點擊按鈕時，網頁主體 SHALL 切換為帶有 #1F2937 背景的深色樣式」。
  3. design.md：規劃使用 Tailwind CSS 的 class="dark" 機制，配合 localStorage 儲存使用者設定的設計細節。
  4. tasks.md：拆解出具體的實作任務（例如 1. 建立按鈕元件、2. 撰寫 JavaScript 切換邏輯、3. 設定 Tailwind 樣式）。

2. 審查提案 (Review)

在提案建立完成後，先別急著寫程式碼。這時候是最佳的審查時機。 人類開發者可以打開 proposal.md 與暫存的 spec.md 來檢視：

  • 「這個需求合理嗎？」
  • 「有沒有漏掉什麼邊界情況（Edge Case），例如：初次載入時應當如何讀取系統預設值？」

如果需要修改，你可以直接跟 AI 溝通：「請將預設值修改為：若 localStorage 沒有設定，則預設讀取系統的 preference（系統深色樣式優先）。」 AI 會使用 /opsx:update 或手動修改這些變更計畫下的 Markdown 檔案。 當團隊（或你個人與 AI 之間）達成共識，就是實作的時候了！

3. 實作任務：opsx:apply

接下來，我們進入實作階段。這時候我們調用指令：

/opsx:apply

AI 助手會讀取 tasks.md 中處於未完成狀態（- [ ]）的任務，並開始修改程式碼。 例如，當 AI 正在處理「任務 1.1：建立切換按鈕元件」時，它會：

  1. 建立 src/components/ThemeToggle.astro 檔案並寫入按鈕結構與 CSS。
  2. 完成後，立刻將 tasks.md 中的該項任務狀態由 - [ ] 改為 - [x]。
  3. 詢問你是否要繼續下一個任務，或是執行測試。

在實作的過程中，如果遇到了「🔴 人工檢查點 (Manual Checkpoint)」，AI 會主動暫停，讓你可以啟動本地的開發伺服器，用瀏覽器看一下按鈕外觀是否正確，確認無誤後再按繼續。

4. 變更驗證：opsx:verify

當所有的實作任務都被勾選為已完成（- [x]）後，我們必須進行變更的驗證：

openspec verify --change "add-dark-mode"

這個指令（或 AI 呼叫的技能）會去檢查本次變更所修改的程式碼，是否真的完全符合在 specs/dark-mode/spec.md 中定義的每一條驗收標準。確認無誤後，這個變更計畫就準備好進行最後的收尾。

5. 合併與歸檔：opsx:archive

最後一步，是將本次變更併入系統的主規格中。我們執行：

/opsx:archive

這個指令會執行兩件事：

  1. 規格合併 (Spec Merge)：將 openspec/changes/add-dark-mode/specs/ 下的規格增量，複製並合併到主規格目錄 openspec/specs/ 下。如果主規格目錄中已經有相同能力（Capability）的規格書，工具會執行智慧合併，將新的情境追加進去。
  2. 清理計畫 (Clean Up)：在確認規格合併完成，且程式碼已提交給 Git 後，工具會將 openspec/changes/add-dark-mode/ 目錄刪除，讓專案重新回到乾淨的狀態。

此時，我們把這些規格的變更隨同程式碼一起 commit 並 push 到遠端 Git，一次完美的 Change 週期就此結束。

總結

一個變更計畫（Change）的旅程如下：

  1. Propose (提案)：模糊想法 $\rightarrow$ 結構化 proposal + spec delta + tasks。
  2. Review (審查)：檢查文字與邏輯，達成共識。
  3. Apply (實作)：一小步一小步修改代碼，並在 tasks 打勾。
  4. Archive (歸檔)：規格增量併入主規格 specs/，刪除臨時變更資料夾。

透過這套週而復始的工作流，專案的規格會跟著程式碼一起「活著」並不斷增長，永遠不會過時。在下一章，我們將詳細介紹 [OpenSpec 目錄結構]，帶你看看規格檔案是怎麼被分類與存放的。