spec-driven-implementation

spec-driven-implementation

在 Warp 中驅動以規格為優先的工作流程，處理重大功能。

概述

對於重大功能使用此技能，書面規格能提升實作品質、減少模糊性，或讓審查更順利。務實看待：並非每個變更都需要規格。

規格通常應存放在：

• specs/<linear-ticket-number>/PRODUCT.md
• specs/<linear-ticket-number>/TECH.md

例如：

• specs/APP-1234/PRODUCT.md
• specs/APP-1234/TECH.md

specs/ 目錄下應僅包含以票號命名的子目錄。請勿在該處建立以工程師命名或功能代號的子目錄。

如果相關的 Linear 議題尚未存在，請在撰寫規格前先建立。直接使用 Linear MCP 工具：

• list_teams 尋找合適的團隊
• list_issue_labels 檢查預期的標籤
• save_issue 以適當的團隊和標籤建立議題

如果從請求與上下文無法明確判斷正確的團隊或標籤，請使用 ask_user_question 釐清，而非自行猜測。

這些規格應主要由代理撰寫，而非手動，並應納入版本控制，以便審查並與程式碼保持同步。

何時需要規格

當變更規模較大時，強烈建議使用規格，例如：

• 產品或架構存在模糊性
• 預估實作規模約 1000 行程式碼以上
• 涉及深層或跨層的堆疊變更
• 有風險的行為變更，回歸成本高昂
• 代理的品質會因更清晰的輸入而顯著提升的工作

以下情況通常不需要規格：

• 小型、局部的錯誤修正
• 直接了當的重構
• 幾乎無模糊性的狹義 UI 調整

對於純 UI 變更，產品規格通常有幫助，而技術規格可能非必要。

工作流程

1. 判斷功能是否需要規格

評估功能的規模、模糊性與風險。如果規格無法有效提升執行或審查品質，則跳過，專注於驗證。

2. 先撰寫產品規格

在實作前，建立 PRODUCT.md 描述預期的使用者面向行為。

使用 write-product-spec 技能來產出。產品規格應定義：

• 要解決的問題
• 預期的使用者體驗
• 不變性與邊界情況
• 成功標準
• 行為將如何驗證

如果功能涉及 UI 或互動設計，詢問是否有 Figma 模型。如果沒有模型，則繼續進行，但需在產品規格中明確標註。

當有 Linear 議題時，在規格中引用該議題。由於規格存放在 specs/<linear-ticket-number>/... 下，這通常很直接。

3. 必要時撰寫技術規格

對於重大或模糊的實作工作，使用 write-tech-spec 技能。

在以下情況優先使用技術規格：

• 實作涉及多個子系統
• 架構或擴充性很重要
• 有值得記錄的重大取捨
• 審查者從審查計畫中獲益比審查原始碼更多

在端到端原型之後再撰寫技術規格是可以接受的，如果這樣能產出更準確的實作計畫。當實作細節仍過於不確定時，不要強迫產出過早的技術規格。

4. 實作已核准的規格

規格核准後，使用 implement-specs 技能根據已核准的 PRODUCT.md 和 TECH.md 進行建置。

實作通常可以與產品和技術規格放在同一個 PR 中推送。當工程師迭代時，將 PRODUCT.md、TECH.md、程式碼變更和測試保持在同一個 PR 中，以便審查反映最終實際發佈的功能。

對於大型功能，實作者可以選擇提供：

• PROJECT_LOG.md 記錄探索路徑、檢查點與當前實作狀態
• DECISIONS.md 記錄設計與實作過程中做出的具體產品與技術決策

這些是選擇性的輔助文件，非必要產出。

5. 在實作過程中保持規格更新

如果實作偏離規格，請更新規格而非讓它過時。

更新 PRODUCT.md 當：

• 使用者面向行為改變
• 成功標準改變
• UX 細節或邊界情況改變

更新 TECH.md 當：

• 實作方法改變
• 架構邊界移動
• 風險、依賴或部署細節改變
• 測試或驗證計畫改變

已納入版本控制的規格應描述最終實際發佈的功能，而非僅是初始意圖。在可行情況下，將這些規格更新與相關程式碼變更放在同一個 PR 中。

6. 根據規格驗證行為

在認為工作完成前，確保驗證能對應回規格。優先使用直接驗證產品行為的測試與產出物：

• 遵循儲存庫本地測試慣例的單元測試與回歸覆蓋
• 針對關鍵使用者流程的整合測試
• 適當的 Loom 導覽或等效功能展示
• 對 UI 密集型工作有用的螢幕截圖或影片

最佳實踐

• 務實為上。
• 撰寫規格是為了提升代理的輸入品質，而非形式主義。
• 產品規格應以行為為導向，避免過多實作細節。
• 技術規格應以實作為導向，並基於當前程式碼庫模式。
• 當規格引用相關程式碼區塊時，盡可能包含已檢查的提交 SHA，並將引用連結到 GitHub 的 blob/<sha>/...#Lx-Ly 精確行數。
• 利用審查時間驗證規格與行為，而非過度關注程式碼風格細節。

相關技能

• implement-specs
• write-product-spec
• write-tech-spec