TechSpecs搜尋

Theme / v1.14.0

OpenSpec

規格驅動開發

主題首頁GitHub ↗
實戰範例

實戰範例 013：用 v1.14.0 的 archived changes 做決策考古

v1.14.0 新功能實戰：用 openspec list --archived 翻出歷史決策、用 openspec view 讀 workflow 狀態、用 version --check 自動化版本檢查。

這個範例要解決的問題

新成員問你：「為什麼我們的認證系統當初選 JWT 而不是 session？」

如果沒有決策紀錄，你只能憑記憶回答，或去 git log 裡考古。OpenSpec 的歸檔變更其實保留了當時的 proposal 與 delta specs——但 v1.13.2 之前，CLI 沒有入口讓你找到它們。

v1.14.0 補上了這個入口。

第一步：翻出歷史決策

openspec list --archived

下列為歷史決策的示意資料，並非 CLI 的實際輸出格式；操作時請使用清單列出的完整歸檔目錄名稱：

Archived changes (12):
  add-user-auth           2026-06-15  ✓ archived
  migrate-to-jwt          2026-07-02  ✓ archived
  add-session-store       2026-05-20  ✓ archived
  ...

想同時看進行中與已歸檔的：

openspec list --all

第二步：讀出當時的決策

找到 migrate-to-jwt 對應的歸檔目錄後，直接讀取其中的 proposal。以下假設清單列出的目錄是 2026-07-02-migrate-to-jwt，請換成你專案的實際名稱：

cat openspec/changes/archive/2026-07-02-migrate-to-jwt/proposal.md

PowerShell 可用 Get-Content openspec/changes/archive/2026-07-02-migrate-to-jwt/proposal.md。openspec show 在 v1.14.0 只查詢進行中的變更與 specs，不能直接查閱歸檔變更。

歸檔目錄保留變更當時實際建立的 artifacts；依 schema 與工作內容，可能包含 proposal、design 與 delta specs——這就是你的決策紀錄。

第三步：用 view 掌握進行中的工作

openspec view

v1.14.0 的 dashboard 現在顯示每個 active change 的 schema 與 artifact 狀態。以下為狀態關係示意，並非 CLI 的逐字輸出：

  add-payment-webhook
    ├── proposal.md    done
    ├── specs/         done
    ├── design.md      ready
    └── tasks.md       blocked
隨堂測驗

dashboard 顯示 `design.md` 是 ready、`tasks.md` 是 blocked。這代表什麼？

💡 想先看個提示？

回顧四種狀態的定義：done / ready / blocked / skipped。

第四步：自動化版本檢查

v1.14.0 新增 openspec version：

openspec version
# npm 全域安裝時的示例：OpenSpec 1.14.0 (npm, global)

openspec version --check --json

JSON 的頂層欄位為 schemaVersion、version、install，加上 --check 時另有 update：

  • version：目前執行的版本
  • install.location、install.packageManager、install.scope：安裝路徑、套件管理器與安裝範圍；無法辨識的資訊可能為 null
  • update.status：available（可更新）、current（目前版本）、disabled（停用檢查）或 offline（無法查證）
  • update.latest：查得的版本，無法查得時為 null
  • update.command、update.canSelfUpgrade：建議更新指令與能否自行更新

CI 應明確處理 disabled 與 offline，不能把它們當成「版本已是最新」。這個指令查的是 CI 執行環境中的安裝版本，不能直接得知其他成員電腦的版本。

第五步：檢查未知 metadata（v1.14.0 誠實化）

openspec validate --strict

如果出現類似下列的警告（文字為示意）：

  ⚠ Unrecognized key in .openspec.yaml: skip_design
    (OpenSpec ignores this; remove it or check the name)

這表示 skip_design 一直以來都被忽略——你以為跳過了 design 階段，其實什麼都沒發生。v1.14.0 讓它變成可見的失敗。

常見誤區

誤區 事實
「歸檔的 change 就找不到了」 list --archived 與 view 都能看到
「ready 就是已完成」 ready 是「可以開始」，done 才是完成
「validate 通過就代表設定生效」 未知 metadata 過去被靜默忽略，--strict 才會揪出
「archive 一定成功」 v1.14.0 起，spec sync 有阻斷條件時 archive 會停止

動手練習

  1. 跑 openspec list --archived 看看你的專案有多少歷史決策
  2. 挑一個歸檔 change，直接讀取歸檔目錄中的 proposal／design，確認當時的設計理由
  3. 跑 openspec validate --strict 檢查是否有被忽略的 metadata

延伸閱讀