真實場景怎麼用：新功能、修 bug、舊專案加入 OpenSpec

前四篇把 OpenSpec 的概念和流程說清楚了，但「知道怎麼跑」跟「到了真實工作知道從哪下手」還是兩回事。這篇拿三個最常見的情境當範本，各自對應一套套路。

情境一：開發新功能

這是最標準的 OpenSpec 使用場景，三個指令就搞定：

套路：explore（可選）→ propose → apply → archive

需求還不清楚？先 explore：

/opsx:explore 用戶回報說搜尋結果排序不對，可能是什麼問題？

AI 會幫你挖 codebase，把現有邏輯說清楚，然後你可以決定要改什麼。想清楚了再 propose：

/opsx:propose fix-search-ranking

AI 生成四份 artifact，你仔細看 proposal.md 和 specs/ 的 delta，確認「對，就是要改這些行為」——這一步的時間不要省，改完實作才發現方向跑偏的代價更高。

確認沒問題，/opsx:apply 實作，/opsx:archive 收尾。

新手常踩的坑：propose 完就直接 apply，沒有確認 artifact。生成的 proposal 和 tasks 有時候會猜偏，尤其是你的需求描述比較模糊的時候，五分鐘確認比實作後重做省多了。

Bug 修復的流程跟新功能幾乎一樣，但有一點差異——要先搞清楚根本原因，不要急著 propose。

套路：explore（定義問題）→ propose → apply → archive

先 explore 把問題說清楚：

/opsx:explore 用戶登入後偶爾 session 會突然失效，尤其在 Safari 上，現有的 session 管理邏輯是怎麼運作的？

AI 挖完 codebase，你們對問題原因有共識了，再 propose：

/opsx:propose fix-safari-session-expiry

這次的 proposal.md 要寫清楚：根本原因是什麼、要修改哪個行為、修完怎樣算 OK。specs 的 delta 裡，如果原本的 spec 有對 session 行為的描述，這次可能是 MODIFIED。

為什麼 bug 修復也要走 OpenSpec？ 因為修完之後，修過的行為就是系統的新現況，應該反映在 spec 裡。下次有人動相同的功能，能在 spec 裡看到這裡有過修復紀錄和決策背景，比從 git blame 挖 commit message 輕鬆很多。

已有專案沒有任何 spec，現在想加入 OpenSpec——不需要把所有東西都補齊再開始用，邊做邊補才是正確姿勢。

套路：init → 為第一個修改建立 change → 每次修改都走 OpenSpec → specs 自然長齊

裝好初始化之後，不要試圖一次把整個系統的 spec 都寫出來——那會變成另一個「先把文件補齊才能動」的死結。

正確的做法：下一次要加功能或修 bug 的時候，就用 OpenSpec 走一遍。/opsx:propose 的時候，AI 生成的 delta spec 會描述這次修改涉及的行為，archive 之後就進 openspec/specs/。就這樣，每次修改一點，specs 慢慢長齊。

如果你想主動補幾個核心 domain 的 spec，可以這樣跟 AI 說：

/opsx:explore 幫我分析 src/auth/ 這個目錄，整理出現有的認證行為，準備寫進 openspec/specs/auth/spec.md

AI 讀完 codebase 之後，你可以直接讓它生成初始 spec 文件，放進 openspec/specs/。不用完美，能捕捉主要行為就夠了。

舊專案常遇到的心理障礙：「現在加是不是太晚了？」不晚。今天加，下一個功能就開始有跑道；不加，一年後還是一樣在猜 AI 跑哪去了。從第一個 propose 開始就是正的。

如果你手上有兩個功能在平行開發——沒問題，OpenSpec 支援：

openspec/changes/
├── add-dark-mode/        ← 你在做
└── fix-search-ranking/   ← 同事在做

各自的 artifact 在各自的資料夾，不打架。Archive 的時候，delta spec 各自合併進對應的 domain spec。

多人協作的時候，可以用 CLI 指令確認狀態：

openspec list          # 列出所有進行中的 change
openspec show add-dark-mode  # 看特定 change 的詳情

五篇讀完，你已經有了一套可以重複用的 OpenSpec 工作套路。下次叫 AI 動工之前，先花十分鐘 /opsx:propose，確認 artifact 對了再 apply——就這一步的紀律，大概率比你之後修改錯誤的代價低太多。