claude-code/claude-zh/skills/tdd-workflow/SKILL.md

name	description
tdd-workflow	在編寫新功能、修復 Bug 或進行程式碼重構時使用。強制執行測試驅動開發 (TDD)，要求包含單元測試、整合測試與 E2E 測試在內的 80% 以上覆蓋率。

測試驅動開發工作流 (TDD Workflow)

本技能確保所有程式碼開發均遵循 TDD 原則，並具備全面的測試覆蓋。

何時啟用

• 撰寫新功能或模組。
• 修復 Bug 或解決已知問題。
• 重構現有程式碼。
• 建立 API 端點。
• 封裝新的組件 (Components)。

核心原則

1. 先寫測試，後寫代碼

務必先編寫測試案例，接著才編寫最少量的程式碼使測試通過。

2. 覆蓋率硬指標

• 整體覆蓋率（單元 + 整合 + E2E）需達到 80% 以上。
• 必須涵蓋所有邊際案例 (Edge Cases)。
• 必須測試錯誤情境 (Error Scenarios) 與邊界條件。

3. 測試類型定義

• 單元測試 (Unit)：測試純函式、工具類、組件邏輯。
• 整合測試 (Integration)：驗證 API 端點、資料庫操作與服務間的交互。
• E2E 測試 (Playwright/Cypress)：模擬真實用戶在瀏覽器中的完整操作流程。

TDD 標準步驟

1. 撰寫用戶旅程 (User Journey)：以使用者視角定義需求。
2. 產出測試案例 (Fail)：先定義 describe 與 it 區塊，此時執行測試應為失敗（紅燈）。
3. 實作最小代碼 (Success)：編寫程式碼直到測試轉為通過（綠燈）。
4. 重構 (Refactor)：在測試通過的前提下優化程式碼品質（如：消除重複、提升效能）。
5. 驗證覆蓋率：執行覆蓋率工具，確保達標。

實踐之最佳實踐

• 測試行為，而非實作：測試使用者看到的結果（如：文字內容），而非內部變數狀態。
• 使用穩健的選取器：在前端測試中優先使用 data-testid 或語義化選取器（如：getByRole），避免使用易變的 CSS Class。
• 測試隔離：每個測試案例應獨立設置其所需數據，避免案例間的相互依賴。
• 模擬外部服務 (Mocking)：對於資料庫、第三方 API（如 OpenAI, Redis）應進行 Mock 處理以保持單元測試的速度與穩定性。
• 一測一斷言：每個測試案例應專注於驗證單一行為。

常見錯誤避免

• ❌ 錯誤：為了測試而測試，忽略了真實的業務邏輯邊界。
• ❌ 錯誤：不維護測試代碼，導致測試變成開發的累贅。
• ✅ 正確：將測試視為開發的一部分，持續優化並與功能同步更新。

---

核心原則：測試不是可選項，它是支撐頻繁重構、快速開發與生產環境穩定性的安全網。