tdd-guide

tdd-guide skill 概覽

tdd-guide 的用途

tdd-guide 是一個用於 Test Driven Development 的 skill，可協助產生單元測試、找出 coverage 缺口、建立 fixtures 與 mocks，並在常見技術棧中引導 red-green-refactor 工作流程。當你希望 AI assistant 不只是「幫我寫幾個測試」時，這個 skill 特別有用：它會把對話推向原始碼、需求、目標框架、coverage reports，以及驗證標準。

最適合的使用者與專案

tdd-guide skill 適合使用 TypeScript、JavaScript、Python 或 Java 的工程團隊、個人開發者，以及重視 QA 的貢獻者。它尤其適合 Jest、Pytest、JUnit、Vitest 與 Mocha 風格的工作流程。當你要為既有程式碼補測試、用 test-first 方式開始新功能、朝某個 coverage 門檻改善覆蓋率，或在團隊內標準化測試輸出時，都很適合使用。

與一般測試 prompt 的差異

一般 prompt 可能會產出看似合理的測試，但常常忽略框架慣例、邊界情境、coverage 優先順序，或 TDD cycle 本身。tdd-guide 內建工作流程結構、範例輸入、預期輸出模式、coverage-analysis tooling、fixture generation、framework adaptation，以及 CI integration 的參考資料。相較於一次性的 prompt 嘗試，它更適合可重複執行的工程工作。

tdd-guide 可能不夠用的情況

tdd-guide for Test Driven Development 不能取代你對領域行為的理解。如果你無法提供預期結果、相依關係、錯誤規則或框架細節，產生出來的測試可能會很表面。它也不會自動保證測試能在你的 repository 中編譯通過；你仍然需要執行本機測試指令，並調整 imports、setup files、mocks，以及環境特定的設定。

如何使用 tdd-guide skill

tdd-guide 安裝與 repository 預覽

在支援 Claude Skills 的環境中，用以下指令安裝這個 skill：

npx skills add alirezarezvani/claude-skills --skill tdd-guide

接著檢視 upstream skill folder：engineering-team/skills/tdd-guide。先從 SKILL.md 開始，了解啟用規則與工作流程，再閱讀 HOW_TO_USE.md 看 invocation examples。如果你需要框架特定的設定，請查看 references/framework-guide.md；如果目標是 build enforcement，請閱讀 references/ci-integration.md；如果想養成更好的 TDD 習慣，請參考 references/tdd-best-practices.md。

讓 tdd-guide 更好用的輸入內容

這個 skill 在你提供四項資訊時效果最好：程式碼或功能需求、語言、測試框架，以及預期行為。好的輸入會包含 happy paths、error cases、boundary values、external dependencies，以及 coverage goals。

較弱的 prompt 是：「Write tests for my auth service。」

更好的 prompt 是：「Use tdd-guide to generate Jest tests for src/auth/password-validator.ts. Cover valid password, too short password, missing uppercase, missing number, missing special character, and null or empty input. Target 90% branch coverage. Use existing project style: describe, beforeEach, and expect(...).toBe(...)。」

實務上的 tdd-guide 工作流程

針對既有程式碼，建議使用以下順序：

1. 貼上或引用 source file。
2. 指定 language、framework，以及 test file naming convention。
3. 要求依優先順序分組產生測試：P0 behavior、P1 edge cases、P2 regressions。
4. 在本機執行產生的測試。
5. 將 compile errors、failing assertions 或 coverage output 貼回 assistant。
6. 要求 skill 修正 imports、mocks、fixtures 與 missing branches。

針對新功能，採用 red-green-refactor：先根據 acceptance criteria 要求產生失敗測試，接著實作最小可通過的程式碼，最後在保持 tests green 的前提下，要求提出 refactor-safe 的改善建議。

優先檢視的實用檔案與 scripts

這個 repository 包含一些實務支援檔案，正式使用前很值得先讀：

• assets/sample_input_python.json 與 assets/sample_input_typescript.json 展示了能提升輸出品質的結構化輸入層級。
• assets/expected_output.json 展示這個 skill 設計上要產出的測試、coverage 與品質摘要類型。
• scripts/test_generator.py 支援 test generation patterns。
• scripts/coverage_analyzer.py 在你有 LCOV、JSON 或 XML coverage data 時很相關。
• scripts/fixture_generator.py、framework_adapter.py 與 tdd_workflow.py 可看出這個 skill 如何理解 mocks、framework conventions 與 TDD phases。

tdd-guide skill 常見問題

tdd-guide 適合初學者嗎？

適合，前提是初學者有具體要測試的功能或函式。tdd-guide skill 可以在產出可用範例的同時，教你 red、green、refactor 的節奏。不過，初學者仍應執行每一個產生出來的測試，並閱讀失敗原因。真正的學習價值來自比較預期行為、產生的 assertions，以及實際 implementation 之間的差異。

tdd-guide 最適合哪些框架？

最適合的是 Jest、Pytest、JUnit 與 Vitest，skill description 中也提到 Mocha。內含的 framework reference 涵蓋 TypeScript/JavaScript、Python 與 Java patterns。如果你使用較不常見的框架，請提供 repository 中的一個範例 test file，讓 skill 能對齊 imports、naming、setup hooks 與 assertion style。

可以分析 coverage reports 嗎？

可以。tdd-guide 設計上可搭配 LCOV、JSON 與 XML 等 coverage reports 使用。為了得到更好的結果，請貼上相關的 uncovered files 與 branches，而不只是提供百分比。像「coverage is 65%」這樣的 prompt，不如分享 coverage/lcov.info、uncovered line ranges，以及與那些缺口對應的 source files 來得有用。

什麼時候不該使用 tdd-guide？

不要把它當成 security-critical、financial、medical 或 compliance-sensitive 行為的唯一品質關卡。它可以協助起草測試並暴露缺口，但若沒有權威規則，無法確認 business correctness。當 codebase 不能分享、沒有定義公開行為，或專案高度依賴隱藏的 integration environments 時，也不太適合使用。

如何改進 tdd-guide skill

用更好的 prompts 改善 tdd-guide 結果

改善 tdd-guide 輸出最快的方法，是提供行為而不只是程式碼。請包含 valid input、invalid input、expected exceptions、boundary values，以及任何既有測試慣例的範例。如果需要 mocks，請點名 dependency，並定義哪些應該 stub、哪些應該真實執行。

有用的 prompt 補充包括：

• “Do not mock the pure calculation function.”
• “Mock the payment gateway and assert it is called once.”
• “Use parameterized Pytest cases for boundary values.”
• “Prefer behavior-focused test names over implementation names.”

修正第一次輸出後常見的失敗模式

常見問題包括 wrong imports、over-mocking、脆弱的 implementation assertions、缺少 async handling，以及只提高 line coverage 卻沒有提升信心的測試。拿到第一次結果後，請貼上 test failure 或 compile error，並要求有針對性的修正。例如：「These Jest tests fail because the service constructor requires a repository dependency. Revise using a typed mock and keep the same behavioral coverage。」

用 coverage data 排定工作優先順序

如果你的目標是改善 coverage，請要求 skill 依風險排序缺口，而不是為每一行未覆蓋程式碼都產生測試。應優先處理未測試的 conditionals、error branches、public methods 與 business rules，再考慮 trivial getters 或 defensive branches。這個 repository 的 coverage workflow 支援 P0/P1/P2 prioritization，通常比單純追逐原始百分比更有用。

反覆迭代，建立可維護的 TDD 實務

tdd-guide 最好的使用方式是反覆迭代。先根據需求要求產生 failing tests，再要求最小 implementation shape，接著請它提出能維持測試穩定的 refactor suggestions。讓 assistant 持續聚焦在可觀察行為：inputs、outputs、side effects、exceptions 與 integration boundaries。這樣產生的測試，才會在 implementation 改變後仍然有價值。