在編寫程式碼之前先建立規格。當開始一個新專案、功能或重大變更，且尚無規格時使用。當需求不明確、模糊或僅存在於模糊概念中時使用。
規格驅動開發
概述
在編寫任何程式碼之前，先撰寫結構化的規格。規格是你與人類工程師之間共享的真相來源——它定義了我們要建置什麼、為什麼，以及如何知道完成。沒有規格的程式碼就是猜測。
使用時機
- 開始一個新專案或功能
- 需求模糊或不完整
- 變更涉及多個檔案或模組
- 你即將做出架構決策
- 任務需要超過30分鐘來實作
何時不使用： 單行修正、錯字更正，或需求明確且自成一體的變更。
閘門式工作流程
規格驅動開發分為四個階段。在當前階段驗證完成之前，不得進入下一階段。
規格 ──→ 計畫 ──→ 任務 ──→ 實作
│ │ │ │
▼ ▼ ▼ ▼
人類 人類 人類 人類
審查 審查 審查 審查
第一階段：規格
從高層次願景開始。向人類提問釐清問題，直到需求具體明確。
立即揭露假設。 在撰寫任何規格內容之前，列出你的假設：
我做的假設：
1. 這是一個網頁應用程式（不是原生行動應用）
2. 認證使用基於 session 的 cookie（不是 JWT）
3. 資料庫是 PostgreSQL（根據現有的 Prisma schema）
4. 我們只針對現代瀏覽器（不支援 IE11）
→ 請現在糾正我，否則我將繼續使用這些假設。
不要默默填補模糊的需求。規格的整個目的就是在程式碼被寫出來之前，揭露誤解——假設是最危險的誤解形式。
撰寫涵蓋以下六個核心領域的規格文件：
-
目標 — 我們要建置什麼以及為什麼？使用者是誰？成功的樣貌是什麼？
-
指令 — 完整的可執行指令及其參數，而不只是工具名稱。
建置：npm run build 測試：npm test -- --coverage Lint：npm run lint --fix 開發：npm run dev -
專案結構 — 原始碼位置、測試位置、文件歸屬。
src/ → 應用程式原始碼 src/components → React 元件 src/lib → 共用工具 tests/ → 單元測試與整合測試 e2e/ → 端對端測試 docs/ → 文件 -
程式碼風格 — 一個真實的程式碼片段勝過三段描述。包含命名慣例、格式化規則，以及良好輸出的範例。
-
測試策略 — 使用什麼框架、測試放在哪裡、覆蓋率期望、哪些測試層級對應哪些關注點。
-
邊界 — 三層系統：
- 總是做： 提交前執行測試、遵循命名慣例、驗證輸入
- 先問： 資料庫 schema 變更、新增相依套件、變更 CI 設定
- 絕不做： 提交機密、編輯 vendor 目錄、未經核准移除失敗的測試
規格範本：
# 規格：[專案/功能名稱]
## 目標
[我們要建置什麼以及為什麼。使用者故事或驗收條件。]
## 技術棧
[框架、語言、主要相依套件及版本]
## 指令
[建置、測試、lint、開發——完整指令]
## 專案結構
[目錄佈局及說明]
## 程式碼風格
[範例片段 + 關鍵慣例]
## 測試策略
[框架、測試位置、覆蓋率要求、測試層級]
## 邊界
- 總是做：[...]
- 先問：[...]
- 絕不做：[...]
## 成功標準
[我們如何知道完成——具體、可測試的條件]
## 待解決問題
[任何需要人類輸入的未解決事項]
將指示重新框架為成功標準。 當收到模糊需求時，將其轉化為具體條件：
需求：「讓儀表板更快」
重新框架的成功標準：
- 儀表板 LCP < 2.5 秒（4G 連線）
- 初始資料載入在 < 500 毫秒內完成
- 載入期間無版面位移（CLS < 0.1）
→ 這些是正確的目標嗎？
這讓你可以反覆嘗試、重試並解決問題，朝著明確的目標前進，而不是猜測「更快」是什麼意思。
第二階段：計畫
根據驗證過的規格，產生技術實作計畫：
- 識別主要元件及其相依關係
- 決定實作順序（哪些必須先建置）
- 記錄風險及緩解策略
- 識別哪些可以平行建置，哪些必須循序進行
- 在階段之間定義驗證檢查點
遵循
planning-and-task-breakdown以了解這些步驟背後的相依圖譜對應與垂直切割機制；它是權威來源。上述項目符號是輕量摘要；若兩者不一致，以planning-and-task-breakdown為準。輸出慣例： 將計畫儲存至
tasks/plan.md，任務清單儲存至tasks/todo.md，遵循/plan指令慣例。若tasks/不存在則建立。後續指令（/build等）預期這些路徑存在。
計畫應可審查：人類應能閱讀並說「是的，這是正確的方法」或「不，請更改 X。」
第三階段：任務
將計畫分解為離散、可實作的任務：
- 每個任務應能在一次專注的 session 中完成
- 每個任務有明確的驗收標準
- 每個任務包含驗證步驟（測試、建置、手動檢查）
- 任務按相依關係排序，而非感知的重要性
- 沒有任務應需要變更超過約 5 個檔案
遵循
planning-and-task-breakdown以了解完整的任務規模與相依排序機制；它是權威來源。以下範本是輕量的內聯形式；若兩者不一致，以planning-and-task-breakdown為準。
任務範本：
- [ ] 任務：[描述]
- 驗收：[完成時必須為真的事項]
- 驗證：[如何確認——測試指令、建置、手動檢查]
- 檔案：[將被觸及的檔案]
第四階段：實作
一次執行一個任務，遵循 skills/incremental-implementation/SKILL.md（incremental-implementation）和 skills/test-driven-development/SKILL.md（test-driven-development）。使用 skills/context-engineering/SKILL.md（context-engineering）在每個步驟載入正確的規格段落和原始檔，而不是將整個規格一次灌給 agent。
保持規格活躍
規格是活文件，而非一次性產物：
- 當決策變更時更新 — 如果你發現資料模型需要變更，先更新規格，再實作。
- 當範圍變更時更新 — 新增或刪除的功能應反映在規格中。
- 提交規格 — 規格應與程式碼一起納入版本控制。
- 在 PR 中引用規格 — 連結回每個 PR 實作的規格段落。
常見合理化藉口
| 合理化藉口 | 現實 |
|---|---|
| 「這很簡單，我不需要規格」 | 簡單的任務不需要長規格，但仍需要驗收標準。兩行的規格也可以。 |
| 「我寫完程式碼後再寫規格」 | 那是文件，不是規格。規格的價值在於在程式碼之前強制釐清。 |
| 「規格會拖慢我們」 | 15 分鐘的規格可以避免數小時的重工。15 分鐘的瀑布式開發勝過 15 小時的除錯。 |
| 「需求無論如何都會改變」 | 這就是為什麼規格是活文件。過時的規格仍然比沒有規格好。 |
| 「使用者知道他們要什麼」 | 即使明確的請求也有隱含假設。規格揭露那些假設。 |
紅旗
- 在沒有任何書面需求的情況下開始寫程式碼
- 在釐清「完成」的定義之前問「我應該直接開始建置嗎？」
- 實作未在任何規格或任務清單中提及的功能
- 做出架構決策卻未記錄
- 因為「要建置什麼很明顯」而跳過規格
驗證
在進行實作之前，確認：
- [ ] 規格涵蓋所有六個核心領域
- [ ] 人類已審查並核准規格
- [ ] 成功標準具體且可測試
- [ ] 邊界（總是做/先問/絕不做）已定義
- [ ] 規格已儲存至儲存庫中的檔案
