指令詳解

/opsx:sync 指令詳解

如何使用 /opsx:sync 將變更計畫中的暫存規格同步至主規格書

指令用途

/opsx:sync 是負責規格合併的指令。它的核心功能是執行智慧合併 (Intelligent Merge)，將變更計畫 (Change) 目錄下專屬的「規格增量 (Spec Delta)」，安全地合併到專案的主規格目錄 openspec/specs/ 中。

透過 /opsx:sync，系統能自動識別哪些需求是新增的、修改的、甚至是刪除的，並精確地將這些改動寫入主規格書，而不會破壞或覆蓋其他不相關的現有規格。

智慧合併運作機制

/opsx:sync 會解析暫存規格書中的四個標準標題區段，並對主規格書進行對應的操作：

  1. ## ADDED Requirements (新增需求)
    • 如果對應的能力 (Capability) 主規格書不存在，自動在 openspec/specs/<capability>/spec.md 建立新檔。
    • 如果主規格書已存在，會將此 Requirement 追加到 Requirements 列表中。
  2. ## MODIFIED Requirements (修改需求)
    • 尋找主規格書中相同的 Requirement。
    • 僅增修提及的部分，例如：只追加新的場景 (Scenario)，或修改既有場景的條件，其餘未提及的場景會完整保留。
  3. ## REMOVED Requirements (移除需求)
    • 在主規格書中尋找對應需求，並將整個需求區塊完整刪除。
  4. ## RENAMED Requirements (重新命名)
    • 使用 FROM: <舊名稱> / TO: <新名稱> 格式定位，將主規格書中的舊需求名稱予以更新。

與 /opsx:archive 的關係

在一般的開發流程中，你很少需要手動執行 /opsx:sync。這是因為當你執行歸檔指令 /opsx:archive 時，工具內部第一步就會自動執行 /opsx:sync。

然而，當你在實作階段，想提早把寫好的規格合併進主分支，讓其他協作者能看見最新規格，或者想提早驗證規格合併後是否有衝突時，手動執行 /opsx:sync 就會非常實用。

實戰對話範例

範例一：同步全新能力（新建主規格書）

  • You: 
    /opsx:sync
  • AI:

    偵測到進行中的計畫為：add-logout-feature。 正在讀取規格增量：specs/logout-flow/spec.md。

    同步結果：

    • 由於主規格中無 logout-flow 能力，已為您新建主規格書：openspec/specs/logout-flow/spec.md。
    • ✓ 已同步 [Requirement: User logout] 與 2 個場景。

    同步完成！

範例二：修改既存能力（追加新場景）

  • You: 
    /opsx:sync
  • AI:

    偵測到進行中的計畫為：add-dark-mode。 正在比對規格增量：specs/dark-mode/spec.md。

    同步結果：

    • 偵測到既存的主規格書：openspec/specs/site-layout/spec.md。
    • ✓ 已在 [Requirement: Theme options] 下，成功追加 [Scenario: User preference fallback]。
    • 主規格書中其餘既存的 5 個場景皆完整保留，不受影響。

    智慧合併成功！

範例三：無須同步時的防呆提示

  • You: 
    /opsx:sync
  • AI:

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

    ⚠️ 無須同步： 該計畫的 specs/ 目錄下沒有任何規格增量檔案，代表本次變更僅涉及程式碼修改與重構，無規格上的異動。