規格驅動功能開發
總覽
此技能強制執行「先規劃、後編碼」的閘道協定。自主編碼代理程式常因直接跳入檔案編輯而失敗，導致語境偏移、幻覺 API 以及耗費 token 在試錯除錯上。
當此技能啟動時，在未草擬、驗證並核准正式規格（SPEC.md 或 .specs/<功能名稱>.md）之前，不得修改任何應用程式程式碼。
1. 第一階段：上下文與限制條件探查
草擬規格前：
- 辨識專案中現有的慣例、資料模型及 API 工具。
- 找到型別定義或 schema 檔案（例如
schema.prisma、drizzle/schema.ts、Zod schemas、OpenAPI 規格）。 - 除非必要，否則不要讀取整個檔案；檢查匯出內容、介面標頭及型別即可。
2. 第二階段：草擬 SPEC.md
閱讀 ./references/spec_template.md 並依照以下精確結構建立 .specs/<功能名稱>.md（或應要求建立在儲存庫根目錄的 SPEC.md）：
- 目標、成功標準與明確的非目標： 清楚的 2 句話問題陳述、確定性的通過標準，以及明確不處理的範圍邊界。
- 資料合約與簽章： 精確的 TypeScript 介面、資料庫欄位型別或 API 架構。
- 檔案修改邊界矩陣： 明確的「建立」、「修改」（標明目標函式/行數）及「禁止」路徑。
- 實作檢查清單與驗證協定： 精確的測試命令、Linter 檢查及邊界案例。
3. 第三階段：閘道檢查點（強制）
產生規格後：
- 互動模式（使用者工作階段）： 呈現簡潔摘要，連結到規格檔案，指出任何架構取捨（若有多種有效方法，使用
ask_question），並在撰寫程式碼前請求確認：「我已在
SPEC.md中草擬規格。請檢視建議的資料合約與檔案邊界矩陣。是否繼續實作？」 - 自主子代理模式： 如果由父層 Lead Orchestrator（例如來自
code-audit-orchestrator）呼叫，且該 Orchestrator 已提供核准的修正計畫，則驗證檔案邊界矩陣與「禁止」路徑零衝突，然後進入第四階段。 - 硬停止： 在互動工作階段中，等待核准或回饋。在獲得綠燈前，不得碰觸原始碼檔案。
4. 第四階段：分階段執行與中途修正協定
核准後：
- 選擇性沙盒隔離： 對於多檔案變更，或當主要工作目錄樹有無關變更時，在修改檔案前，透過
git-worktree-isolator佈建隔離的工作目錄樹。 - 以離散、原子化的里程碑實作功能（例如 Schema $\to$ 核心邏輯 $\to$ API 處理器 $\to$ 使用者介面/整合）。
- 在規格檔案中，隨著里程碑完成標記進度核取方塊。
- 讓 git 提交保持在單一里程碑範圍內。
應急措施：中途規格修正
如果實作過程中發現未預見的限制（例如「禁止」檔案必須修改、上游 SDK 型別與草擬的合約不符、或使用者在進行中修改需求）：
- 立即停止受影響里程碑的編輯。
- 在規格檔案的
## 6. 規格修正（增量日誌）區段中新增一筆記錄，包含：- 觸發條件/阻礙因素： 為何原始合約無法維持。
- 修正區段與增量變更： 資料合約或檔案修改邊界矩陣的精確變更。
- 如果增量變更觸及先前標記為「禁止」的檔案，或改變了公開 API / schema 合約，則暫停並請求使用者快速確認後再繼續。如果增量變更純屬內部（例如提取內部的輔助檔案），則在規格中記錄增量變更並繼續執行。
5. 第五階段：驗證與歸檔
- 執行第二階段中指定的確定性測試套件。
- 確認所有型別檢查與 Linter 都乾淨通過。
- 將規格狀態更新為「已完成」，並歸檔至
.specs/completed/YYYY-MM-DD-<功能名稱>.md（若儲存庫不追蹤.specs/目錄，則移除暫存規格檔案）。