修訂一項變更的現有規劃成品,並維持它們之間的一致性。永不編輯程式碼。
儲存庫選擇: 如果使用者指定了一個儲存庫(store,一個在本機註冊的獨立 OpenSpec 儲存庫),或者工作位於某個儲存庫內,執行 openspec store list --json 來探索已註冊的儲存庫 ID,然後在讀取或寫入規格與變更的命令(如 new change、status、instructions、list、show、validate、archive、doctor、context)中加上 --store <id> 參數。其他命令不接受此旗標。命令輸出的提示資訊已包含該旗標;在後續操作中請保留它。若沒有儲存庫,則命令作用於最近的本機 openspec/ 根目錄。
輸入:可選擇性地指定一個變更名稱。若省略,則檢查是否能從對話上下文推斷。若不明確或有歧義,你必須提示使用者選擇可用的變更。
步驟
-
若未提供變更名稱,提示使用者選擇
執行
openspec list --json取得按最近修改時間排序的可用的變更。然後使用 AskUserQuestion 工具讓使用者選取要更新的變更。將最近修改的前 3-4 個變更作為選項呈現,顯示:
- 變更名稱
- Schema(來自
schema欄位(若存在),否則顯示 "spec-driven") - 狀態(例如 "0/5 tasks"、"complete"、"no tasks")
- 最近修改時間(來自
lastModified欄位)
將最近修改的變更標記為 "(Recommended)",因為這很可能是使用者想要更新的變更。
重要:切勿猜測或自動選取變更。務必讓使用者自行選擇。
-
取得變更的成品
openspec status --change "<name>" --json解析 JSON 以了解當前狀態。回應包含:
schemaName:正在使用的工作流程 Schema(例如 "spec-driven")artifacts:成品陣列,包含其狀態("done"、"ready"、"blocked")isComplete:布林值,表示所有成品是否皆已完成planningHome、changeRoot、artifactPaths和actionContext:路徑與範圍上下文。使用這些來取代假設的回購庫本機路徑。
成品 ID 和路徑來自活躍的 Schema——不要對它們做任何假設,也不要基於硬編碼的成品名稱進行分支判斷。自訂 Schema 必須能不加修改地正常運作。
要編輯的檔案是
artifactPaths.<id>.existingOutputPaths——存在於磁碟上的具體檔案,對於 glob 成品已進行過 glob 展開(例如specs/**/*.md)。不要寫入resolvedOutputPath:對於 glob 成品,它仍然是 glob 模式,而非真實檔案。 -
理解請求
- 如果使用者要求特定的修訂("設計現在使用 X"),那就是起始編輯。
- 如果他們只說 "update" / "make this coherent",則將其視為一致性審查:讀取現有成品,並檢查它們彼此之間是否存在矛盾、缺口和重複。
-
讀取與調和
- 讀取請求所觸及的一個或多個成品,以及該變更的其他現有成品。
- 套用請求的編輯。然後檢查其他每個現有成品與之是否一致——任何方向皆可:對較晚成品的編輯可能需要修訂較早的成品,反之亦然。構建順序是建議的閱讀順序,而非對哪些成品可以被修訂的限制。
- 記錄所有現在不一致、缺失或矛盾的內容。
- 僅修訂已存在的檔案(
existingOutputPaths)。不要建立尚不存在的成品,也不要在 glob 成品下發明新檔案——將其記錄下來,並引導使用者使用/opsx:continue來建立它們。 - 如果變更已經是一致的,請告知使用者並不做任何編輯。
-
逐個成品確認並套用
- 顯示每個建議的修訂及其原因。僅在使用者確認後才寫入。
- 如果使用者拒絕某個修訂,則不要寫入——保持該成品不變。
- 當需要大幅重寫時,先取得該成品的規則和範本:
openspec instructions <artifact-id> --change "<name>" --json
-
指出下一步(僅供指引——切勿實際執行)
- 仍有缺失的成品 -> 建議使用
/opsx:continue來建立它們。 - 變更已實作(任務已勾選/已完成套用)-> 程式碼可能不再符合修訂後的計畫;建議使用
/opsx:apply來將差異帶入程式碼。 - 所有事項已完成且已實作 -> 建議使用
/opsx:archive。
- 仍有缺失的成品 -> 建議使用
輸出
每次呼叫後,顯示:
- 哪些成品被修訂了(以及哪些提議的修訂被拒絕了)
- 任何推遲到
/opsx:continue的事項(尚未建立的成品或檔案) - 變更的當前狀況與建議的下一個命令
護欄
- 僅限規劃成品——永不編輯實作程式碼。如果修訂後的計畫暗示了程式碼變更,請停止並引導至
/opsx:apply。 - 使用
openspec status報告的成品 ID 和路徑;切勿基於硬編碼的成品名稱進行分支判斷。 - 僅編輯
existingOutputPaths中的具體檔案;切勿寫入 glob 的resolvedOutputPath。 - 不要推進構建前沿:不要建立新的成品,不要在 glob 成品下建立新檔案——這是
/opsx:continue的職責。 - 在寫入之前,每次編輯都必須取得使用者確認。
- 如果請求改變了變更的意圖而非只是優化它,建議使用
/opsx:new重新開始(即「更新 vs. 重新開始」的啟發式判斷)。