tdd-guide

tdd-guide skill 概览

tdd-guide 适合用来做什么

tdd-guide 是一个面向 Test Driven Development 的 skill，可用于生成单元测试、发现覆盖率缺口、创建 fixtures 和 mocks，并在常见技术栈中指导 red-green-refactor 流程。当你希望 AI assistant 不只是“写一些测试”，而是围绕源代码、需求、目标框架、覆盖率报告和验证标准展开工作时，tdd-guide 会更有价值。

最适合的用户和项目

tdd-guide skill 适合使用 TypeScript、JavaScript、Python 或 Java 的工程团队、独立开发者，以及偏 QA 的贡献者。它尤其适用于 Jest、Pytest、JUnit、Vitest 和 Mocha 风格的工作流。你可以在这些场景中使用它：为现有代码补测试、用测试先行的方式启动新功能、把覆盖率提升到某个阈值，或在团队内统一测试输出方式。

它和普通测试 prompt 有什么不同

普通 prompt 可能会生成看起来合理的测试，但经常忽略框架约定、边界场景、覆盖率优先级，甚至 TDD 循环本身。tdd-guide 内置了工作流结构、示例输入、预期输出模式、覆盖率分析工具、fixture 生成、框架适配，以及 CI 集成参考。相比一次性的 prompt 试验，它更适合可重复的工程实践。

什么时候 tdd-guide 可能还不够

tdd-guide for Test Driven Development 不能替代你对业务领域行为的理解。如果你无法提供预期结果、依赖关系、错误规则或框架细节，生成的测试可能会比较浅。它也不能自动保证测试一定能在你的仓库中编译通过；你仍然需要运行本地测试命令，并根据项目情况调整 imports、setup files、mocks 和环境相关配置。

如何使用 tdd-guide skill

安装 tdd-guide 并预览仓库

在兼容 Claude Skills 的环境中安装该 skill：

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

然后查看上游 skill 目录 engineering-team/skills/tdd-guide。建议先从 SKILL.md 开始，了解激活规则和工作流；再阅读 HOW_TO_USE.md，查看调用示例。如果你需要特定框架的设置说明，检查 references/framework-guide.md；如果目标是构建阶段强制执行测试，阅读 references/ci-integration.md；如果想改善 TDD 习惯，查看 references/tdd-best-practices.md。

让 tdd-guide 更好发挥作用的输入

这个 skill 在你提供四类信息时效果最好：代码或功能需求、语言、测试框架，以及预期行为。高质量输入通常包括 happy paths、错误场景、边界值、外部依赖和覆盖率目标。

较弱的 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. 粘贴或引用源文件。
2. 指定 language、framework 和测试文件命名约定。
3. 要求按优先级分组生成测试：P0 行为、P1 边界场景、P2 回归。
4. 在本地运行生成的测试。
5. 将编译错误、失败断言或覆盖率输出贴回给 assistant。
6. 让 skill 继续细化 imports、mocks、fixtures 和遗漏分支。

针对新功能，采用 red-green-refactor：先根据验收标准要求生成会失败的测试，再实现最小可通过代码，最后在保持测试通过的前提下请求可安全重构的改进建议。

建议先查看的文件和脚本

仓库里包含一些实用支持文件，正式使用前很值得先读：

• assets/sample_input_python.json 和 assets/sample_input_typescript.json 展示了怎样的结构化输入能提升输出质量。
• assets/expected_output.json 展示了该 skill 设计上会产出的测试、覆盖率和质量摘要类型。
• scripts/test_generator.py 支持测试生成模式。
• scripts/coverage_analyzer.py 适用于你拥有 LCOV、JSON 或 XML 覆盖率数据的情况。
• scripts/fixture_generator.py、framework_adapter.py 和 tdd_workflow.py 能看出该 skill 如何理解 mocks、框架约定和 TDD 阶段。

tdd-guide skill 常见问题

tdd-guide 适合初学者吗？

适合，前提是初学者有一个具体的功能或函数要测试。tdd-guide skill 可以在产出可用示例的同时，帮助理解 red、green、refactor 的节奏。不过，初学者仍然应该运行每一个生成的测试，并认真阅读失败信息。真正的学习价值来自对比预期行为、生成的断言和实际实现。

tdd-guide 对哪些框架支持最好？

最匹配的是 Jest、Pytest、JUnit 和 Vitest，skill 描述中也提到了 Mocha。随附的框架参考覆盖了 TypeScript/JavaScript、Python 和 Java 的常见模式。如果你使用的是较少见的框架，请提供仓库中的一个示例测试文件，这样 skill 才能匹配 imports、命名方式、setup hooks 和断言风格。

它能分析覆盖率报告吗？

可以。tdd-guide 设计上支持处理 LCOV、JSON 和 XML 等覆盖率报告。为了获得更好的结果，建议粘贴相关的未覆盖文件和分支，而不仅仅是一个百分比。类似 “coverage is 65%” 的提示不如直接分享 coverage/lcov.info、未覆盖行范围，以及与这些缺口相关的源文件有用。

什么时候不应该使用 tdd-guide？

不要把它作为安全关键、金融、医疗或合规敏感行为的唯一质量门禁。它可以帮助起草测试并暴露缺口，但在没有权威业务规则的情况下，无法确认业务正确性。当代码库不能共享、没有定义公开行为，或项目严重依赖隐藏的集成环境时，它也不太适合。

如何改进 tdd-guide skill 的使用效果

用更好的 prompt 提升 tdd-guide 结果

提升 tdd-guide 输出质量最快的方法，是提供行为，而不只是代码。包括有效输入、无效输入、预期异常、边界值，以及已有测试约定。如果需要 mocks，请明确依赖名称，并说明哪些应该 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.”

修正首次输出后的常见问题

常见问题包括 imports 错误、mock 过度、对实现细节的脆弱断言、缺少 async 处理，以及只提升行覆盖率却没有提升信心的测试。拿到第一版结果后，把测试失败信息或编译错误贴出来，并要求有针对性地修正。例如：“These Jest tests fail because the service constructor requires a repository dependency. Revise using a typed mock and keep the same behavioral coverage.”

用覆盖率数据确定工作优先级

如果你的目标是提升覆盖率，应该让 skill 按风险对缺口排序，而不是为每一行未覆盖代码都生成测试。优先处理未测试的条件分支、错误分支、public methods 和业务规则，再考虑简单的 getters 或防御性分支。该仓库的覆盖率工作流支持 P0/P1/P2 优先级划分，这比单纯追逐原始百分比更有价值。

逐步形成可维护的 TDD 实践

使用 tdd-guide 的最佳方式是迭代。先根据需求要求生成失败测试，再请求最小实现形态，然后要求在保持测试稳定的前提下给出重构建议。让 assistant 始终聚焦于可观察行为：输入、输出、副作用、异常和集成边界。这样生成的测试即使在实现变化后仍然有用。