如何在既有專案中採用 Spec Kit
你不必先從規格重建既有系統,才能使用 Spec Kit。直接在原地初始化儲存庫,記錄重要的規則,並把工作流程用在下一項有邊界的變更上。
1. 從可審查的基線開始
初始化之前,先提交或暫存既有工作,並為這次採用建立分支。這樣每個產生的檔案都能在一般的程式碼審查中看見。
為你使用的程式代理選擇整合鍵。接著從儲存庫根目錄執行命令:
specify init --here --force --integration <key>
--here 以目前目錄為目標。--force 允許在非空目錄中初始化,並可能取代受管理路徑上衝突的檔案,所以請只在建立可審查的基線之後使用。它不會刪除應用程式的其餘部分。
繼續之前,先檢視產生的差異。初始化會加入共用的 .specify/ 專案檔案,以及你所選整合所需的命令或 skill 檔案。它不會改寫你的應用程式,也不會為既有行為推斷規格。
注意
Git 初始化與功能分支是選用的,由 git 擴充功能管理。若你想要那套工作流程,用 specify extension add git 加入它。
2. 記錄專案護欄
其餘步驟以一個範圍有限的功能為例,說明如何採用 SDD。如果你的第一項任務是修復問題,可以在初始化後改走錯誤修正快速入門;若要評估提案,則使用構想評估快速入門。這兩種流程都不需要先完成下面的 SDD 步驟。
以下範例使用 GitHub Copilot 的預設 skills 模式(/speckit-*)。請在代理的對話中逐一呼叫各項 skill,不要在終端機中執行,並在進入下一步之前先檢閱結果。
使用 /speckit-constitution,帶入儲存庫中已經成立、或團隊已明確同意採用的原則:
/speckit-constitution Preserve public API compatibility. Follow the existing
service boundaries. Every database migration must include a rollback plan.
Run the repository's established unit and integration test suites.
以儲存庫的 README、架構決策、貢獻指南與 CI 設定作為證據。不要只為了填滿憲章範本就編造標準。憲章會治理後續的計畫與分析,不切實際的規則只會製造雜訊,而不是有用的限制。
3. 選擇一項有邊界的第一項變更
從一項可獨立審查的功能或現代化切片開始。不要把「記錄整個既有系統」當成第一項功能,除非那份盤點本身就是預期的交付物。
同時描述要求的成果,以及必須保持完整的相容性邊界:
/speckit-specify Add CSV export to the existing orders page. Preserve current
filters and authorization behavior. Export only the rows visible to the signed-in
user, and do not change the existing JSON API response.
程式碼庫仍是實作脈絡。新的 spec.md 定義的是你打算做的變更,而不是對每一項既有行為的事後規格。
4. 對照儲存庫進行計畫
繼續走一般的工作流程:
- 執行
/speckit-clarify,釐清不確定的行為與相容性需求。 - 執行
/speckit-plan,確認提議的設計重用了既有的架構、相依性與測試慣例。 - 執行
/speckit-tasks,再執行/speckit-analyze,在實作前檢查一致性。 - 執行
/speckit-implement,並一起檢閱程式碼與產出物的變更。 - 執行
/speckit-converge找出尚存的落差。如果它補上了任務,請重複實作與收斂,直到功能完成。
命令詳情與選用的品質關卡,請見快速入門指南與代理式 SDD 參考。
5. 決定規格如何演進
完成第一次變更後,先就團隊要保留哪些功能產出物、以及如何維護保留的產出物達成共識。保存規格頁面比較了這些選擇,包括在僅保留憲章的模型下退役已完成的功能產出物。交付後續變更時,請使用演進規格指南。
既有專案範例
社群導覽包含跨 .NET、Java 與 Go/React 程式碼庫的棕地範例。用於架構探索與棕地初始化的社群擴充功能,列在擴充功能型錄。
另請參閱
- 命令呼叫 — 其他程式代理與整合模式的語法。