tdd
Test-Driven Development methodology and red-green-refactor workflow (formerly test-tdd). This skill should be used when practicing TDD, writing tests first, designing tests before implementation, or reviewing test-first approaches. Triggers on "write tests first", "test before code", "red green refactor", "test driven development". This skill does NOT cover Vitest framework specifics (use vitest skill) or API mocking with MSW (use msw skill).
- Installs
- 411
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/pproenca/dot-skills --skill tdd- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads tdd automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Community Test-Driven Development Best Practices
Comprehensive guide to Test-Driven Development practices, designed for AI agents and LLMs. Contains 42 rules across 8 categories, prioritized by impact to guide test writing, refactoring, and code generation.
When to Apply
Reference these guidelines when:
- Writing new tests using TDD workflow
- Implementing the red-green-refactor cycle
- Designing test structure and organization
- Creating test data and fixtures
- Reviewing or refactoring existing test suites
TDD Workflow
- RED: Write a failing test that defines desired behavior
- GREEN: Write minimal code to make the test pass
- REFACTOR: Clean up code while keeping tests green
- Repeat for each new behavior
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Red-Green-Refactor Cycle | CRITICAL | cycle- |
| 2 | Test Design Principles | CRITICAL | design- |
| 3 | Test Isolation & Dependencies | HIGH | isolate- |
| 4 | Test Data Management | HIGH | data- |
| 5 | Assertions & Verification | MEDIUM | assert- |
| 6 | Test Organization & Structure | MEDIUM | org- |
| 7 | Test Performance & Reliability | MEDIUM | perf- |
| 8 | Test Pyramid & Strategy | LOW | strat- |
Quick Reference
1. Red-Green-Refactor Cycle (CRITICAL)
cycle-write-test-first- Write the Test Before the Implementationcycle-minimal-code-to-pass- Write Only Enough Code to Pass the Testcycle-refactor-after-green- Refactor Immediately After Greencycle-verify-test-fails-first- Verify the Test Fails Before Writing Codecycle-small-increments- Take Small Incremental Stepscycle-maintain-test-list- Maintain a Test List
2. Test Design Principles (CRITICAL)
design-test-behavior-not-implementation- Test Behavior Not Implementationdesign-one-assertion-per-test- One Logical Assertion Per Testdesign-descriptive-test-names- Use Descriptive Test Namesdesign-aaa-pattern- Follow the Arrange-Act-Assert Patterndesign-test-edge-cases- Test Edge Cases and Boundariesdesign-avoid-logic-in-tests- Avoid Logic in Tests
3. Test Isolation & Dependencies (HIGH)
isolate-mock-external-dependencies- Mock External Dependenciesisolate-no-shared-state- Avoid Shared Mutable State Between Testsisolate-deterministic-tests- Write Deterministic Testsisolate-prefer-stubs-over-mocks- Prefer Stubs Over Mocks for Queriesisolate-use-dependency-injection- Use Dependency Injection for Testability
4. Test Data Management (HIGH)
data-use-factories- Use Factories for Test Data Creationdata-minimal-setup- Keep Test Setup Minimaldata-avoid-mystery-guests- Avoid Mystery Guestsdata-unique-identifiers- Use Unique Identifiers Per Testdata-builder-pattern- Use Builder Pattern for Complex Objects
5. Assertions & Verification (MEDIUM)
assert-specific-assertions- Use Specific Assertionsassert-error-messages- Assert on Error Messages and Typesassert-no-assertions-antipattern- Every Test Must Have Assertionsassert-custom-matchers- Create Custom Matchers for Domain Assertionsassert-snapshot-testing- Use Snapshot Testing Judiciously
6. Test Organization & Structure (MEDIUM)
org-group-by-behavior- Group Tests by Behavior Not Methodorg-file-structure- Follow Consistent Test File Structureorg-setup-teardown- Use Setup and Teardown Hooks Appropriatelyorg-test-utilities- Extract Reusable Test Utilitiesorg-parameterized-tests- Use Parameterized Tests for Variations
7. Test Performance & Reliability (MEDIUM)
perf-fast-unit-tests- Keep Unit Tests Under 100msperf-avoid-network-calls- Eliminate Network Calls in Unit Testsperf-fix-flaky-tests- Fix Flaky Tests Immediatelyperf-parallelize-tests- Parallelize Independent Testsperf-avoid-sleep- Avoid Arbitrary Sleep Calls
8. Test Pyramid & Strategy (LOW)
strat-test-pyramid- Follow the Test Pyramidstrat-mutation-testing- Use Mutation Testing to Validate Test Qualitystrat-coverage-targets- Set Meaningful Coverage Targetsstrat-integration-boundaries- Test Integration at Service Boundariesstrat-e2e-critical-paths- Limit E2E Tests to Critical User Paths
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
- cycle-write-test-first - Write the Test Before the Implementation
- design-aaa-pattern - Follow the Arrange-Act-Assert Pattern
Related Skills
- For Vitest framework specifics, see
vitestskill - For API mocking with MSW, see
mswskill
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md
FAQ
What does the tdd skill do?
Test-Driven Development methodology and red-green-refactor workflow (formerly test-tdd). This skill should be used when practicing TDD, writing tests first, designing tests before implementation, or reviewing test-first approaches. Triggers on "write tests first", "test before code", "red green refactor", "test driven development". This skill does NOT cover Vitest framework specifics (use vitest skill) or API mocking with MSW (use msw skill).
How do I install tdd?
Run npx skills add https://github.com/pproenca/dot-skills --skill tdd in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tdd/ (personal) or .claude/skills/tdd/ (project).
Which AI agents can use tdd?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is tdd safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains tdd?
It is published by pproenca in pproenca/dot-skills. It has 411 recorded installs.
More from pproenca/dot-skills
zod
pproenca/dot-skills
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
vitest
pproenca/dot-skills
Vitest testing framework patterns for test setup, async testing, mocking with vi., snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
react-hook-form
pproenca/dot-skills
React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, useFieldArray, the subscribe() API, and the Watch / FormStateSubscribe / FieldArray render-prop components. Covers RHF 7.82 additions including resetDefaultValues() and the disabled field-array option. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).
emilkowal-animations
pproenca/dot-skills
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
nuqs
pproenca/dot-skills
nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
clean-architecture
pproenca/dot-skills
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
Popular testing & qa skills
tdd
mattpocock/skills
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
grilling
mattpocock/skills
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
migrate-to-shoehorn
mattpocock/skills
Migrate test files from as type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace as in tests, or needs partial test data.
run-train
lllllllama/rigorpilot-skills
Rigor Train skill for deep learning research repositories. Use when a documented or selected training command should be run conservatively for startup verification, short-run verification, full kickoff, or resume, with command, config, seed, log, checkpoint, status, and metric evidence written to standardized trainoutputs/. Do not use for environment setup, exploratory sweeps, speculative idea implementation, or end-to-end orchestration.
test-driven-development
obra/superpowers
Use when implementing any feature or bugfix, before writing implementation code
finishing-a-development-branch
obra/superpowers
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work