BriarForge/dev-grill-spec-driven

盤問，然後規格驅動開發

兩個工作流程，接續執行，之間有一次交接：

1. 盤問（Matt Pocock，grill-me → to-spec）：以設計樹的形式逐輪訪談使用者，直到沒有任何隱含假設為止。然後將已達成的共識綜合成一份規格，不提出任何新問題。
2. 建構（DeepLearning.AI + JetBrains，使用編碼代理進行規格驅動開發)：規格以 requirements.md、plan.md 和 validation.md 的形式存放在儲存庫中一個帶日期的目錄下，按任務群組在其專屬分支上實作，根據 validation.md 驗證，記錄在變更日誌中，合併，並重新規劃路線圖。

盤問取代了 SDD 課程中固定的三個問題訪談（範圍 / 決策 / 背景），改用完整的設計樹訪談。SDD 課程則取代了 to-spec 的「發佈到問題追蹤器」，改用與程式碼並存且隨之變更的規格文件。

概述

使用時機：當變更規模大到先寫下規格比重做更划算時：例如新功能、路線圖階段、MVP 衝刺、或為舊有程式碼庫加入 SDD。一行修正或純粹的錯誤追查（請用 pstack-engineering 找根本原因）則跳過。

觸發詞句：「grill me then spec it」、「grill to spec」、「spec-driven」、「SDD」、「feature spec」、「work on the next phase」、「start the next feature」。

硬性關卡（絕不可跳過）：

• 在使用者確認盤問已達成共享理解之前，不得撰寫任何規格文件（關卡 A）。
• 在使用者批准規格文件之前，不得撰寫任何程式碼（關卡 B）。
• 在 validation.md 中的每一項都通過之前，不得合併任何內容（關卡 C）。

執行說明

在一開始解析 SPECS=${SDD_SPECS_DIR:-specs} 和 BASE=${SDD_BASE_BRANCH:-<儲存庫預設分支>}。以下路徑均相對於專案根目錄。

階段 0 — 定位（事實是你的工作）

1. 閱讀專案的 AGENTS.md / CLAUDE.md、README.md 以及任何詞彙表或 ADR。遵循儲存庫自身的 git 規則（包裝器、分支命名、禁止強制推送）。
2. 檢查是否存在憲章：$SPECS/mission.md、$SPECS/tech-stack.md、$SPECS/roadmap.md。
   • 全部存在 → 前往階段 1 處理下一個功能。
   • 缺失，新專案 → 第一次盤問將針對憲章本身（使命、目標受眾、技術棧差距）。其產出即為三個文件，其中 roadmap.md 應拆分為非常小的階段，每個階段均可獨立交付。
   • 缺失，現有程式碼庫（舊有） → 先探索程式碼，根據實際情況（技術棧、慣例、已交付的功能作為已完成階段）起草憲章，然後僅盤問差距和未來的路線圖。
3. 如果使用者未指定功能名稱，則目標是下一個階段：路線圖中第一個所有項目均未勾選（[ ]）的部分。
4. 探索該功能將觸及的程式碼。永遠不要問使用者那些儲存庫、工具或文件可以回答的問題。如果主體架構允許，可將廣泛的探索委託給一個新的子代理，並且不要讓不相關的問題阻塞它。

階段 1 — 盤問（設計樹訪談）

徹底訪談使用者，直到達成共享理解。將計劃視為一棵設計樹：每個決策都會分支為依賴於它的決策。

• 以輪次進行。前緣是每個先決條件已解決、但本身尚未決定的開放決策。在一輪中提出整個前緣，然後等待。
• 為每個問題編號並提供你的推薦答案。措辭應使「是」代表接受該推薦。
• 依賴於本輪中另一個仍開放的問題的問題，應歸屬於後續輪次。
• 在整個過程中，至少應涵蓋 SDD 的各個軸向：範圍（它收集、暴露、做什麼；資料形狀）、決策（儲存、可見性、驗證、UX 模式、架構）、背景（語調、限制、技術棧限制、開放問題），以及測試介面：該功能將在何處被測試。優先選擇現有介面和可能中最高層級的介面；理想情況是只有一個。
• 新的依賴項、schema 變更和公開 API 變更始終是明確的問題，絕非假設（tech-stack.md 是權威）。

輪次格式：

❓ **Q1** - **<標題>**: <問題，如果有選項>

➡️ <推薦答案>

---

❓ **Q2** - ...

如果主體架構具有結構化問題工具（Claude Code 的 AskUserQuestion），你可以將其用於最多四個選擇題的輪次；否則使用上述文字格式。

當前緣為空時，盤問結束。用一個簡短的列表總結已確定的決策，並請使用者確認。

關卡 A： 在使用者確認總結之前，不得繼續。

階段 2 — 轉為規格（綜合，無新問題）

將對話轉化為規格。不要再次訪談；如果確實出現了差距，則表示盤問遺漏了一個分支：僅詢問那一個問題，然後繼續。

1. 從 $BASE 建立分支：路線圖階段使用 phase-<N>-<kebab-name>，否則使用 feature/<kebab-name>（或儲存庫自身的慣例）。
2. 重新閱讀 $SPECS/mission.md 和 $SPECS/tech-stack.md，以及現有功能規格以了解風格。
3. 建立 $SPECS/YYYY-MM-DD-<feature-name>/（使用今天的日期），並根據 references/spec-templates.md 撰寫三個文件：
   • requirements.md — to-spec 的內容（問題、解決方案、詳盡編號的使用者故事清單、實作決策、測試決策、不包含的範圍）加上 SDD 的範圍/決策/背景章節。不包含檔案路徑或程式碼片段，除非是一個經過修剪的原型片段，其精確度勝過文字描述。
   • plan.md — 編號的任務群組，每個群組均可獨立實作和測試，並包含編號的子任務。
   • validation.md — 自動化檢查（確切指令）、人工逐步操作、邊界情況、使用者介面文字的語調檢查，以及完成的定義。
4. 可選，如果使用者要求或儲存庫使用 issue 追蹤工作：也將需求發佈為一個 issue（gh issue create）並從 requirements.md 連結它。
5. 向使用者展示這三個文件（路徑加上簡短的摘要）。

關卡 B： 等待批准。回饋意見（例如「為 X 加入一個任務群組」、「元件應放在自己的檔案中」）首先應用於規格，並且保持所有文件同步。

階段 3 — 實作

1. 依序實作任務群組。每個群組完成後：執行專案的測試和型別檢查，提交並附上命名該群組的訊息，在 plan.md 中勾選其方塊。
2. 如果實作顯示規格有誤或不完整，請在與偏離規格的程式碼相同的提交中更新規格。規格和程式碼永不偏離。
3. 彼此沒有依賴關係的群組可以交給並行的子代理（每個在其自己的工作樹中；遵循主體的工作樹規則），由你合併回來。
4. 未經使用者批准，不得加入新的依賴項，即使某個群組「需要」它。

階段 4 — 驗證

1. 執行 validation.md 中的每個自動化檢查，並貼上真實輸出。
2. 逐步執行人工檢查（對於 UI，實際操作：瀏覽器自動化或截圖，而非「應該可行」）。
3. 可選的深度審查：從三個觀點（正確性、規格符合性、可維護性）針對分支差異產出審查者，然後修正阻礙點。
4. 詢問使用者是否需要根據建構結果釐清規格。

關卡 C： 每個「完成的定義」項目都通過，或者使用者明確豁免其中一個（在 validation.md 中記錄該豁免）。

階段 5 — 閉環

1. 在 $SPECS/roadmap.md 中將該階段標記為完成（[x]）。
2. 更新 CHANGELOG.md（# Changelog，## YYYY-MM-DD 標題最新者優先，每個有意義的變更一個項目符號，自上次記錄日期起）。如果存在專案的 changelog 技能則使用之。
3. 提交，切換到 $BASE，合併分支，刪除它，根據儲存庫規則推送。
4. 重新規劃： 詢問是否有任何學到的東西改變了 mission.md、tech-stack.md 或路線圖（合併、拆分或重新排序階段）。跨領域的決策（例如「使用 Vitest」、「響應式 UI」）應放入 tech-stack.md / mission.md，並回溯應用到現有規格。
5. 提供下一個階段：它從階段 1 重新開始。

環境變數

變數	預設值	描述
SDD_SPECS_DIR	specs	憲章和功能規格目錄，相對於專案根目錄
SDD_BASE_BRANCH	儲存庫預設分支	功能分支從此分支建立並合併至此

驗證檢查清單

• 在任何功能規格之前，憲章已存在（mission.md、tech-stack.md、roadmap.md）
• 每個盤問問題都附有推薦答案提出；沒有詢問儲存庫可以回答的事實
• 在撰寫任何規格文件之前，使用者已確認決策總結（關卡 A）
• requirements.md、plan.md、validation.md 存在於功能分支上的 $SPECS/YYYY-MM-DD-<名稱>/ 下
• 在撰寫任何程式碼之前，使用者已批准規格（關卡 B）
• 每個任務群組提交時測試通過；計劃方塊已勾選
• 只要實作偏離規格，規格即已更新
• 所有 validation.md 檢查均已執行並附上真實輸出（關卡 C）
• 路線圖階段已勾選、變更日誌已更新、分支已合併並刪除
• 已提出重新規劃的問題

已知陷阱

• 無限盤問。 盤問在前緣為空時結束，而非在你用完好奇心時。不要重新詢問已確定的決策；不要詢問屬於程式碼審查範疇的細節。
• 在轉為規格階段進行訪談。 階段 2 是綜合；其中的新問題意味著盤問不完整。僅詢問那一個缺失的問題，而非進行第二次訪談。
• 在關卡 A/B 之前撰寫。 SDD 課程明確規定：在訪談得到回答之前，不要將任何內容寫入磁碟。在規格批准之前撰寫程式碼違背了該方法。
• 階段過大。 無法在一次審查中看完的階段，應在規格制定前於路線圖中拆分。
• 規格偏離。 實作中途要求的變更，應先應用於規格，再應用於程式碼。不再匹配程式碼的規格比沒有更糟。
• 需求中包含檔案路徑。 它們很容易過時；請改為描述模組和介面（路徑最多屬於 plan.md 的子任務）。
• 儲存庫規則優先。 來自儲存庫 AGENTS.md 的分支名稱、推送包裝器、工作樹位置和歸屬規則，將覆蓋此處的預設值。

請參閱 references/spec-templates.md 以取得文件範本，references/sources.md 以了解每個部分的來源。