如何在既有專案中演進規格

當需求變更,或實作過程中的發現需要修改既有功能時,請使用本指南。內容涵蓋如何把下一個預期的合約明確寫出、並據此交付,而不是交付後該保留哪些產出物。

如果儲存庫尚未用 Spec Kit 初始化,請先參閱在既有專案中採用 Spec Kit。

評估變更

確認受影響的行為,並檢閱現有的功能產出物、實作、測試,以及持續維護的設計或產品文件。區分「違反已約定意圖的缺陷」與「提議變更該意圖」兩種情況。實作是討論的證據,不是需求的替代來源。

判斷這項發現改變的是預期行為、實作策略、任務拆解,還是只有程式碼。發現可能源自規格、計畫、任務清單或實作,包括交付過程中產生的發現。來源為何,並不決定哪份產出物具有權威性。

明確寫出修正後的意圖

從乾淨的工作樹或專用分支開始,讓每項產出物變更都可供檢閱。決定要建立新的功能目錄或修改保留的產出物時,遵循團隊選定的保存慣例。如果先前的功能產出物已經退役,請用持續維護的需求與決策紀錄建立脈絡,不要假設只靠憲章就能完整描述該功能。

  1. 在 spec.md 中寫出預期的合約。使用 /speckit.specify 在 specs/ 下建立新的功能目錄,或修改既有的規格。
  2. 執行 /speckit.plan 或修改 plan.md,定義實作方式。
  3. 執行 /speckit.tasks 或修改 tasks.md,推導出工作拆解。
  4. 執行 /speckit.analyze,在實作前回報跨產出物的不一致之處。

核心沒有專門的命令會自動調和 spec.md、plan.md 與 tasks.md 之間的差異。Analyze 只會回報不一致,不會編輯產出物。請直接調和,或依擴充功能的文件說明使用擴充功能。替換衍生產出物之前,請先保留重要的實作理由。

如果團隊接受了一項改變意圖的發現,請將這項共識反映到受影響的產出物中。不要讓任務或程式碼中的低層級變更,與理應保持可信的規格互相矛盾。

交付並評估變更

所有保存模型都使用相同的交付/完成流程: specify -> plan -> tasks -> implement -> converge。

  1. 針對明確寫出的預期產出物執行 /speckit.implement。
  2. 檢閱產出的實作與產出物差異。
  3. 執行 /speckit.converge,在憲章的規範下,對照規格、計畫與任務評估實作。
  4. 如果 converge 為尚存的落差補上任務,請重複實作與收斂,直到約定的功能完成。

Converge 只會附加內容:它唯一可能的寫入,是把尚待完成的工作加入 tasks.md。它不會重寫產出物,把程式碼當作文件化意圖的替代品。Analyze 與 converge 都不會選擇保存策略,擴充功能提供的調和也不會改變這些核心命令的職責。

只修改產出物,並不會自行交付變更後的行為。當修改需要實作時,請完成這個交付循環。交付完成後,再另外套用團隊的保留與維護政策。

另請參閱

  • 保存規格 - 決定交付後留存的內容,以及如何維護保留的產出物。
  • 升級 Spec Kit - 更新受管理的專案檔案,而不是變更功能需求。