如何在交付後保存規格
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 的自動行為。
退役功能產出物
交付與檢閱完成後:
- 將歷久彌新的需求、驗收標準與決策保存到約定的歸屬。只有在治理原則或約束變更時才修訂憲章;不要把它變成一堆功能規格的集合。
- 依團隊的保留政策,對外封存功能產出物或將其丟棄。如果檢閱者仍需要它們,請在移除本機副本之前,提供約定的檢閱位置。
- 將未來的交付產出物排除在版本控管之外,或透過經過檢閱的變更移除已完成且受追蹤的產出物。把
specs/加入.gitignore並不會取消追蹤已提交的檔案,也不會清除儲存庫歷史。
選擇模型
模型是團隊慣例,不是 CLI 設定。專案甚至可以在不同區域使用不同模型,只要貢獻者知道哪個區域適用哪種模型。
| 模型 | 交付後維護規則 | 最適用於 | 注意事項 |
|---|---|---|---|
| 回流規格 | 將已接受的發現反映到任何成品中,然後調和 | 快速迭代與緊密協作 | 成品之間無聲偏離 |
| 前進規格 | 為新需求建立新的功能目錄 | 稽核軌跡與歷史清晰度 | 上下文重複或碎片化 |
| 活規格 | 編輯 spec.md;重新產生衍生成品 |
規格即合約 | 重新產生的檔案遺失理由 |
| 僅保留憲章 | 保留憲章;將已完成的功能產出物從儲存庫退役 | 交付產出物,歷久彌新的知識在別處維護 | 需求或理由因缺乏長久歸屬而遺失 |
如果你的團隊尚未選定模型,請先回答三個問題:
- 已完成的功能產出物應該留在儲存庫中嗎?如果不留,歷久彌新的需求與決策要存放在哪裡,產出物會封存還是丟棄?
- 如果保留,已完成的功能目錄應該是歷史紀錄,還是可編輯的工作區?
- 保留的
spec.md是唯一的真實來源,還是允許plan.md與tasks.md成為同等地位的來源?
一旦答案明確,請將慣例記錄在專案憲章或團隊入門說明中,讓未來的貢獻者知道如何處理變更。
另請參閱
- 演進規格 - 明確寫出意圖,並在選定的保存慣例下交付後續變更。