/opsx:archive 指令詳解

指令用途

/opsx:archive 是變更計畫 (Change) 生命週期的終點。當你完成所有實作任務（tasks.md 全數勾選）並且通過驗證（verify）後，執行此指令來關閉該計畫，將暫存的規格增量 (Spec Delta) 正式合併至主規格，並將計畫目錄移動到歸檔資料夾中，以保持專案結構的乾淨。

運作流程

1. 選擇計畫：若未指定名稱，AI 助手會讀取當前專案，或提示你選擇一個進行中的 Change。
2. 檔案與任務完整度檢查：
   • 檢查是否所有必要規劃產物（proposal, design, specs, tasks）狀態皆為 done。
   • 讀取 tasks.md，檢查是否還有未完成的任務。若發現有 incomplete tasks，AI 會發出警告並確認你是否仍要強制歸檔。
3. 規格增量分析與合併：
   • 比對變更計畫下的 specs/ 與系統主規格目錄 openspec/specs/，向你展示本次歸檔即將對主規格進行的修改摘要。
   • 提示你是否立即執行同步（/opsx:sync）。
4. 搬移與清理：
   • 建立 openspec/changes/archive/ 目錄（若不存在）。
   • 產生帶有日期前綴的歸檔名稱：YYYY-MM-DD-<change-name>。
   • 執行 mv 指令將計畫資料夾移動到 archive/ 目錄下。

實戰對話範例

範例一：無警告順利歸檔

• You:

  /opsx:archive
  

• AI:

  偵測到進行中的變更計畫：add-logout-feature。

  規劃與任務狀態確認：

  • ✓ 規劃產物：4/4 均已完成。
  • ✓ 實作任務：3/3 均已勾選為完成。

  規格同步分析 (Spec Sync)： 本次將同步全新能力：openspec/specs/logout-flow/spec.md。

  正在執行同步並搬移目錄⋯⋯

  Archive Complete

  Change: add-logout-feature Archived to: openspec/changes/archive/2026-07-14-add-logout-feature/ Specs: ✓ 已成功同步至主規格書。

  計畫歸檔完成！本地工作目錄已重回乾淨狀態。

範例二：有未完成任務時的警告提示

• You:

  /opsx:archive
  

• AI:

  偵測到進行中的變更計畫：add-logout-feature。

  ⚠️ 發現未完成任務警告：

  • 檢測到 tasks.md 中尚有 1 項任務「3.3 撰寫單元測試」尚未完成 (- [ ])。

  請問您是否確定要忽略此警告並繼續歸檔？(若繼續，此計畫資料夾仍將被移至 archive 目錄) (Y/N)

範例三：無規格增量的單純程式碼修改歸檔

• You:

  /opsx:archive
  

• AI:

  偵測到進行中的變更計畫：refactor-logging-system。

  規劃與任務狀態確認：

  • ✓ 任務與文檔均已全數完成。
  • 📝 本次變更未包含 specs/ 目錄，無須進行規格同步。

  正在執行搬移目錄⋯⋯

  Archive Complete

  Change: refactor-logging-system Archived to: openspec/changes/archive/2026-07-14-refactor-logging-system/ Specs: 無規格異動 (Skipped)。