❯❯ 紅燈，是我寫給 AI 最清晰的規格書！/feature-to-ui 如何用 TDD 與五階段管線 2 天蓋完 11 個模組

📍 流水線位置｜入口 → flow → 型別 → mock → 測試 → 【UI】 → vibe → 上線

規格、flow、型別、Mock API、E2E 測試合約，前面幾天把這些全都設定好了，但前端畫面一頁都還沒有產出。這時候跑 E2E 測試，不出意外地直接跳出一整片紅燈。

不過在這條流水線裡，這批紅燈並不是要修補的 Bug，而是我們的派工單。接下來就交給 /feature-to-ui 帶著 AI 對照著這些失敗的測試合約，一個模組一個模組把 11 個業務介面填補起來，直到測試全部通過。

兩天內，搞定 11 個模組

這是我婚禮專案 Git Log 記錄下的開發軌跡：

06/20  scaffold（專案骨架與基底配置）
06/20  regenerate per-feature gherkin
06/21  add e2e business flows for all 11 modules
06/21  add contract types, mock API, typed client and route map
06/21  add business contract specs and test helpers
06/21  implement module pages, layouts, stores and auth guard

短短兩天內，11 個模組的流程文件、介面合約、Mock API 以及 E2E 測試腳本全數到位。最後，在單單一個 Commit 裡，直接把實體頁面、Layout、Pinia Store 與路由守衛（Auth Guard）一口氣蓋完，隨即發出 Pull Request。

一個 commit 就能吃下整個 UI 層，全靠前面數個 commit 所累積的上百條測試斷言（核心主 spec 後續擴充至 150 條）。介面實作啟動的那一刻，AI 手上早已拿到一份明確、而且完全無法任意改動的驗收標準。

一次只讓 AI 想一件事

AI 只要一次載入太多 Context，就容易開始產生幻覺或漏掉規範。所以 /feature-to-ui 被設計成五階段管線，讓 AI 在每一個階段都只專注做好一件事：

這個開發順序並非憑空想像，而是我過去手寫專案時累積下來的習慣。當初設計這支 Prompt 時，我只思考了一個核心問題：「過去我自己拿到需求時，是怎麼拆解步驟的？」接著照這個節奏切分下去就對了。

不過，傳統上拆解步驟是為了排程與團隊分工，但這裡的目的完全不同：分階段設計，是為了精準掌控 LLM 的 Context Window。如果把路由、版面、元件規範、表單驗證與錯誤處理一口氣塞給 AI，只會稀釋它的注意力，讓格式違規與邏輯遺漏的機率大幅飆升。

為了落實「按需載入（Load on Demand）」原則，專案中的規範檔案採取標籤化管理。以 references/rules.md 為例，每個段落標題都標上了對應的 Phase 標籤（如 [P1, P3, P4, P5]）。配色策略會被其中四個階段讀取，而 Zod 表單驗證規範只有在 Phase 5 載入。這讓SKILL.md主控檔能精簡在 185 行內，其餘 2,966 行的細節規範則拆分成 9 個參考檔，等需要時才動態載入。

遇到了特定領域的需求（例如 HLS 串流、SSE 傳輸或複合表單驗證）也是同一套邏輯，系統只會在對應的階段補充專屬的領域上下文（Domain Context），確保 AI 在專注的範疇內精確執行。

紅燈就是最精準的工單 | 閘門控制與對照表機制

拆分階段解決了「AI 一次想太多」的問題，但接著面臨另一個關鍵：做出來的東西到底對不對，誰說了算？

為了確保 Phase 5 產出的程式碼能符合合約，腳本在它前面設了四道關卡：

1. Spec 閘門（Gatekeeper）：
test/e2e/specs/ 底下找不到對應的 spec 檔，Phase 5 直接無法啟動。我規範定義 .spec.ts 是 UI 的唯一合約；頁面元件用的 data-testid 必須直接從測試腳本的 getByTestId() 複製過來，AI 不能自己隨便取名。

2. 強制讀取實體路徑：
動工前，AI 必須先翻 server/api/ 的真實檔案結構，讀完即將呼叫的 API 端點原始碼、型別定義、共用元件與 Store，不許憑空假設路徑、更不許自己偷訂型別。如果 API 不存在，就必須先回頭把 API 蓋出來，絕不允許跳過。

3. Spec → UI 對照表：
寫 code 之前，AI 要先從 Spec 的測試標題提取情境，輸出一張「Spec → UI 對照表」。做完逐項對照驗收，確認沒有遺漏才能交件。

4. 一頁一停交覆機制：
一次只做一個頁面。完成後產出情境覆蓋表，流水線隨即暫停，並印出下一頁的發起指令（如 /feature-to-ui 5 {頁面名}）。我在規則中明確禁止 AI 吐出「要我繼續嗎？」這類非標準的廢話詢問。

這個暫停機制跟 OpenSpec 的變更流程有著本質上的差異：OpenSpec 的確認點是在問「變更計畫對不對」，工程師必須重新切回規格思維去審核；而 Phase 5 的確認點只問「測試對照表打勾了沒」，因為業務合約早在 Spec 階段就已經凍結，審核的認知成本低得多。

當頁面實作完成後，接力棒就會交給測試鏈的指令（先用 /test e2e red 收集失敗清單，再用 /test e2e green 一路修到通過），正式進入修復與驗證的迴圈：跑測試、解析錯誤訊息、修復介面程式碼、重跑測試。在這個迴圈裡，測試結果就是最客觀、還能自我驗證的即時回饋。

6/21 那天實際跑的當然不只一支測試，但這套機制的最小運作單位就是如此：紅燈給出明確的失敗原因，程式碼改對了，重跑之後燈自然變綠。

下面是我後來抓其中一支測試來重現這個迴圈的真實輸出（這是為了示範特別整理的最小版本，並不是當天那份一片紅燈的完整報告）：

• 紅：strict mode violation，測試給出明確的失敗原因（重現示範；這份輸出的事故背景）
  
• 綠：修對地方後重跑，同一支測試通過（重現示範）
  

在這段開發過程中，我的角色變得非常奇妙：我不再是那個一行行手寫 Code 的人，也不是無微不至下達微觀指令的指揮官，反而更像是一個坐在現場的監工。偶爾抬頭看一眼進度，只要確定紅燈數量持續下降就好。

因為真正的品質把關，早在昨天把 Spec 寫好的那一刻，就已經通通完成了。

全綠的那一刻

當最後一盞紅燈轉為綠燈時，那一刻的工程價值，絕不只是「程式碼寫完了」，而是這套系統所定義的所有業務行為，都已經正式通過自動化腳本的嚴格驗證。

沒有測試防線保護的 AI 生成，產出的只是「表面上看起來沒問題的程式碼」，後續往往需要耗費大量人工手動點擊來驗收；而有了測試防線護航的 AI 生成，驗收過程早已被自動化封裝，產出的是「經過領域合約嚴格檢驗」的系統實作。

看到這裡，你可能已經發現了：先出紅燈、再對著紅燈把程式碼修到全綠，這正是測試驅動開發（TDD）經典的紅綠節奏。過往傳統開發常把「先寫測試」當成拉長開發時程的負擔；但在結合 LLM 的自動化流水線中，這個思考框架被徹底翻轉：

紅燈，是我寫給 AI 最清晰無誤的一份規格書。

如果沒有失敗的測試作為邊界，AI 只能對著模糊的需求做機率性的盲猜；有了明確的紅燈與斷言條件，AI 才擁有了精確的執行目標與即時的反饋迴路。先寫測試由一種流程約束，轉化為加速系統建構的核心工程槓桿。

而這批紅燈劃出的邊界，並不是 AI 自己憑空想像。每一條斷言都從 flow 文件的業務行為與商業不變量翻譯而來，再往上追溯，就是最源頭的 feature 規格。AI 加速的只是「抵達綠燈」的過程，但邊界到底要劃在哪裡，始終由業務需求決定。

至此，前半段流水線已順利將抽象規格，一路鍛造成全數綠燈的堅固系統。

雖然系統功能已經完備，但目前的介面呈現還只是基礎原型。
下一篇，我會分享如何在「不破壞任何一條綠燈合約」的前提下，進行介面視覺與互動體驗的現代化重構。

🎒 最小一步｜ 在讓 AI 寫新元件之前，先建一支必定失敗的 E2E 測試，並要求 AI 只能靠修改該元件把測試修到綠燈。
📎 本篇證據｜ git log 2026-06-20 ~ 06-21（commit 軌跡與 PR #2）、.claude/skills/feature-to-ui/（五階段架構、Phase 5 Spec Gate、references/rules.md 標籤分組）