功能開發流程
主要原則：代理人自行做出的決定越少，結果越穩定。 每個階段結束時都會產出一個成品，存放在 docs/features/<slug>/ 中，並經過檢查（「閘門」）。凡有標記之處，需經人工確認後才能進入下一階段。
如何撰寫程式碼 — fsd-frontend；垃圾檢查 — anti-slop-review；登入與工作階段 — frontend-auth-session。
1. 階段
| # | 階段 | 成品 | 核准者 | 閘門 |
|---|---|---|---|---|
| 0 | 準備 | 分支 | — | 工作目錄乾淨；安裝依賴與遷移後，執行 /clear |
| 1 | PRD | prd.md | 人 | 非目標已填寫；驗證標準可測試；無技術方案 |
| 2 | 規格 | spec.md，最多 150 行 | 人 | 涵蓋所有 PRD 驗證標準，不超出範圍 |
| 3 | 任務 | tasks.md | 人 | 一項任務一個提交；第一個為追蹤子彈 |
| 4 | 研究 | 記錄在 tasks.md | — | 僅讀取；找出可重複使用的內容 |
| 5 | 追蹤子彈 | 提交 | — | 一個情境完整貫穿並可在瀏覽器中查看 |
| 6 | 建構 | 每項任務一個提交 | — | 邏輯部分先寫測試；pnpm check 通過 |
| 7 | 審查 | reviewer 報告 | 人（根據發現） | 已確認的發現已修正 |
| 8 | 瀏覽器 | 關鍵路徑的 e2e 測試 | — | PRD 情境在無控制台錯誤下通過 |
小型任務（一個提交，無對使用者的新行為）可跳過階段 1–3，但非目標仍須記錄在任務描述中。跳過階段時必須明確說明，而非默默進行。
2. PRD
範本 — docs/features/_template/prd.md。
- 代理人根據請求草擬初稿，僅詢問無法繼續進行的必填事項。其他內容歸入「待解決問題」，由人在核准時確認。
- 非目標為必填。 列出代理人可能會順便想做的事情：適應新尺寸的響應式設計、動畫、i18n、快取、管理後台、重構相鄰程式碼。沒有這份清單，功能會不斷蔓延。
- 完成標準必須可測試：使用「給定 / 當 / 則」格式，而非「好用」或「快速」。
- 不提及任何函式庫、檔案或架構：這是關於「什麼與為什麼」的問題，不是「如何做」。
3. 規格
範本 — docs/features/_template/spec.md。
- 最多 150 行。由代理人撰寫，由人核准。冗長的生成規格比沒有還糟：它會塞滿上下文並模糊決策。
- 撰寫前，先進行簡短的唯讀檢視受影響的層級：現有內容、可重複使用的部分。
- 內容包括：程式碼所在位置（層級、切片）、資料合約（zod 結構、DTO 對應）、API（輸入、輸出、錯誤 →
kind）、UI 狀態、邊界案例、含測試層級的驗收情境。 - 規格與程式碼共存。 行為變更時，應在同一提交中修改
spec.md。程式碼若與規格不一致，則為兩者之一的缺陷。
4. 任務
範本 — docs/features/_template/tasks.md。
- 一項任務一個提交，提交後專案應可建構且檢查通過。若代理人陷入死胡同，回溯到前一個提交比與模型爭論更省成本。
- 任務應能在同一工作階段內完成；每項任務都有「完成條件」。
- 第一個任務為追蹤子彈，後續為狀態處理、邊界案例、打磨。
5. 研究（僅讀取）
每項任務前，不修改檔案：
- 受影響資料夾中的
AGENTS.md； - 解決類似問題的現有程式碼（使用
rg搜尋名稱與合約）； - 任務所依賴的合約與型別。
若之後需要記錄已發現的內容，在 tasks.md 中新增 2–3 行記錄。
6. 追蹤子彈
一個貫穿完整的情境：路由 → 頁面 → 功能或實體 → request() → 路由處理器或後端 → 畫面結果。
- 這是正式程式碼，不是原型：正確的層級、真實的規格合約。
- 刻意不包含：詳細驗證、載入與錯誤狀態的打磨、樣式、邊界案例。
- 若後端尚未就緒，使用 MSW 處理器或路由處理器，根據規格合約回傳資料；此情況應在
tasks.md中標記。 - 驗證在瀏覽器中進行：情境應通過，且控制台無錯誤。
7. 建構
- 邏輯部分 — 先寫測試： 純函式、狀態管理、回應對應、含分支的 hooks。測試應因預期原因而失敗，然後才撰寫程式碼。事後才寫的測試傾向於驗證程式碼做了什麼，而非應該做什麼。
- 版面與樣式 — 不預先寫測試： 這些由瀏覽器（階段 8）驗證，關鍵路徑由 e2e 測試涵蓋。
- 每項任務後：執行
pnpm check，然後提交（lint-staged 會檢查修改過的檔案）。 - 停止條件： 針對同一問題連續三次修正失敗 — 停止。向人說明嘗試過的方法與假設。不要為了通過測試而修改測試、關閉 lint 規則或放寬型別。
- 所有超出任務範圍的變更應記錄在「待辦」中，而非寫入此提交。
8. 審查
- 子代理人
reviewer（.claude/agents/reviewer.md）應取得全新上下文：傳入prd.md與spec.md的路徑以及提交範圍；它會自行讀取 diff。程式碼作者較難發現自己的錯誤，因為其上下文中充滿了證明方案正確的論據。 - 已確認的發現應修正，有爭議的由人決定。
- 安全事項應由人檢查： 登入、工作階段、重導向、cookie、使用者輸入插入 HTML。通過自動檢查不代表萬無一失：實務上，開放式重導向可能通過測試，無法閱讀的錯誤頁面則可能通過 lint 檢查。
9. 瀏覽器
- Next.js：若已安裝，使用
next-dev-loop技能搭配agent-browser；否則使用 Playwright 或 Chrome DevTools MCP。 - 執行 PRD 中的情境，包括負面測試：空資料、網路錯誤、重複提交。檢查控制台與請求狀態碼。
- UI 部分：檢查淺色與深色主題、手機寬度。
- 關鍵路徑應有 e2e 測試，放在
e2e/中。 - 完成條件：每個 PRD 驗證標準均已檢查；最終訊息應列出每個標準及其驗證方式。
10. 上下文
- 工作進度存放於
docs/features/<slug>/，而非對話記錄中：新工作階段應從讀取prd.md、spec.md、tasks.md開始。 - 噪音較多的步驟（安裝、遷移、長日志）之後，執行
/clear。 - 平行實驗應使用
git worktree，而非工作分支。
11. 不應做的事項
- 無盡的追問：僅詢問會阻礙進度的問題，其餘歸入 PRD 中的假設。
- 由多個代理人組成的協調器：僅需執行者與審查者即可。
- 無人核准或閱讀的規格與文件。
- 默默跳過階段或「順便修正」。