如何在交付後保存規格

Spec Kit 有意讓團隊自行決定功能交付後,spec.md、plan.md 與 tasks.md 的去向。這套工具組提供可重複的工作流程,但不強制採用單一成品維護策略。

本頁介紹四種模型,讓團隊能明確做出這個選擇。沒有任何一種是預設值,Spec Kit 也不強制採用其中任何一種。

四種模型都保留憲章作為專案的總體規格:即規範每個功能的原則、約束與品質期望。功能規格描述正在交付的行為。這些模型的差異在於,沿著這個共同基礎保存了哪些功能產出物,而不是憲章是否繼續規範專案。

交付共用,保存各自獨立

保存是團隊的選擇:決定交付後要保留並維護哪些內容,而不是另一種交付或判定完成的方式。四種模型都使用相同的交付流程。在任何模型下,發現與產出物調和都可能在交付過程中發生;發生的時機並不決定保存策略。

兩個獨立的問題

規格驅動開發有一個時間維度的問題:規格應該重要多久?一篇 SDD 工具概覽將其生命週期分為三個層級:

  • 規格優先(Spec-first):先寫規格再寫程式,之後允許丟棄規格。
  • 規格錨定(Spec-anchored):實作後保留規格,並用於後續變更。
  • 規格即原始碼(Spec-as-source):將規格視為唯一由人編輯的原始來源,並從中重新產生實作成品。

Spec Kit 也提出第二個問題:交付後應該保存哪些功能產出物,保留的產出物在需求變更時又該如何演進?以下模型描述的就是這種保留與維護策略。

回流規格(Flow-Back Spec)

當 spec.md、plan.md、tasks.md 與實作彼此都能互相提供資訊時,採用回流模式。

交付後,已接受的發現可作為任何成品維護編輯的依據。團隊決定這些發現對預期行為、技術作法或任務拆解意味著什麼。團隊可以自行調和 spec.md、plan.md 與 tasks.md,或使用有文件說明會執行此工作的擴充功能。實作是該討論的證據,而不是取代意圖的來源。

回流模式在以下情況運作良好:

  • 團隊夠小,能快速注意到並調和偏差
  • 預期實作發現會重塑原始計畫
  • 速度比將每個中間決策保存為不可變歷史更重要

主要風險是無聲的偏離。如果團隊變更了較低層級的成品,卻未將決策反映回 spec.md,未來的貢獻者可能不知道該信任哪份成品。

前進規格(Flow-Forward Spec)

當每個功能目錄都應保留為歷史紀錄時,採用前進模式。

在此模型中,已完成的成品被視為不可變。當需求變更時,團隊會建立新的功能目錄,而不是修改既有的 spec.md、plan.md 或 tasks.md。舊目錄仍可用於稽核、比較,或解釋專案如何走到目前的狀態。

前進模式在以下情況運作良好:

  • 稽核能力與可追溯性很重要
  • 功能範疇明確,且很少原地重訪
  • 團隊希望隨時間清楚呈現需求變更的順序

主要的取捨是重複。相關決策可能散落在多個功能目錄中,因此團隊需要命名、連結或檢閱習慣,讓沿革容易追蹤。當新目錄取代或延伸先前的工作時,請使用清楚的功能名稱或交叉連結。

活規格(Living Spec)

當 spec.md 是合約、其他成品則由它衍生時,採用活規格模式。

交付後,團隊將 spec.md 維護為合約:當預期行為變更時先更新它,再從該來源重新產生或修訂 plan.md 與 tasks.md。計畫與任務清單仍然有價值,但它們被視為可拋棄的衍生物,而不是永久的真實來源。

活規格在以下情況運作良好:

  • 產品合約夠穩定,能主導工作流程
  • 團隊樂於在規格變更後重新產生衍生成品
  • 需求與實作之間的一致性,比保留每個中間計畫完整無缺更重要

主要風險是,若衍生成品在未將重要決策保存在其他地方的情況下被丟棄,可能遺失有用的實作理由。

僅保留憲章(Constitution-Only)

當憲章應該是版本控管中、Spec Kit 交付產出物集合裡唯一長期存在的文件時,請使用僅保留憲章模型。

功能產出物仍透過共用的交付流程支援規格制定、計畫、實作與檢閱。交付後,團隊將它們從儲存庫的維護內容中退役。它們可以對外封存,例如隨 pull request 封存,或存放在有保存期限的產出物儲存區,也可以依團隊的保留政策丟棄。這是規格優先的生命週期選擇,不是交付期間跳過功能規格的做法。

憲章仍是專案的總體規格,但它無法取代功能需求、驗收標準或實作理由。在退役產出物之前,請先把任何歷久彌新的知識保存到約定的歸屬,例如持續維護的產品文件、設計紀錄或議題追蹤器。僅保留憲章並不表示憲章是專案唯一留存的文件。

僅保留憲章模型適合以下情況:

  • 團隊希望功能產出物僅用於交付,事後不再維護
  • 歷久彌新的需求與決策已有另一個持續維護的歸屬
  • 讓產生的功能產出物不進入儲存庫歷史,可以減少雜訊

Spec Kit 自身的儲存庫就是這種選擇的例證:它追蹤 .specify/memory/constitution.md,而 specs/ 已加入 gitignore,功能產出物不受追蹤。歷久彌新的知識也存在於設計文件、文件、測試與貢獻者指引中。將功能產出物排除在版本控管之外,並不等於說明它們是被刪除還是封存。

主要的風險是遺失意圖與理由,而這些內容無法靠重新產生產出物可靠地復原。對外封存與刪除是團隊自有的政策,不是 Spec Kit 的自動行為。

退役功能產出物

交付與檢閱完成後:

  1. 將歷久彌新的需求、驗收標準與決策保存到約定的歸屬。只有在治理原則或約束變更時才修訂憲章;不要把它變成一堆功能規格的集合。
  2. 依團隊的保留政策,對外封存功能產出物或將其丟棄。如果檢閱者仍需要它們,請在移除本機副本之前,提供約定的檢閱位置。
  3. 將未來的交付產出物排除在版本控管之外,或透過經過檢閱的變更移除已完成且受追蹤的產出物。把 specs/ 加入 .gitignore 並不會取消追蹤已提交的檔案,也不會清除儲存庫歷史。

選擇模型

模型是團隊慣例,不是 CLI 設定。專案甚至可以在不同區域使用不同模型,只要貢獻者知道哪個區域適用哪種模型。

模型 交付後維護規則 最適用於 注意事項
回流規格 將已接受的發現反映到任何成品中,然後調和 快速迭代與緊密協作 成品之間無聲偏離
前進規格 為新需求建立新的功能目錄 稽核軌跡與歷史清晰度 上下文重複或碎片化
活規格 編輯 spec.md;重新產生衍生成品 規格即合約 重新產生的檔案遺失理由
僅保留憲章 保留憲章;將已完成的功能產出物從儲存庫退役 交付產出物,歷久彌新的知識在別處維護 需求或理由因缺乏長久歸屬而遺失

如果你的團隊尚未選定模型,請先回答三個問題:

  1. 已完成的功能產出物應該留在儲存庫中嗎?如果不留,歷久彌新的需求與決策要存放在哪裡,產出物會封存還是丟棄?
  2. 如果保留,已完成的功能目錄應該是歷史紀錄,還是可編輯的工作區?
  3. 保留的 spec.md 是唯一的真實來源,還是允許 plan.md 與 tasks.md 成為同等地位的來源?

一旦答案明確,請將慣例記錄在專案憲章或團隊入門說明中,讓未來的貢獻者知道如何處理變更。

另請參閱

  • 演進規格 - 明確寫出意圖,並在選定的保存慣例下交付後續變更。