Use when implementing features or fixing bugs with strict Test-Driven Development (TDD). Activate for coding tasks that require new functionality, refactoring, or comprehensive test coverage, especially when the user mentions TDD or Test Driven Development.
Use when implementing features or fixing bugs with strict Test-Driven Development (TDD). Activate for coding tasks that require new functionality, refactoring, or comprehensive test coverage, especially when the user mentions TDD or Test Driven Development.
TDD Methodology Expert
Enforce and reinforce Test-Driven Development (TDD) methodology throughout the software development process. This skill provides comprehensive guidance, automated validation, and continuous reinforcement of the Red-Green-Refactor cycle.
When to Use This Skill
This skill automatically activates when:
TDD is mentioned in CLAUDE.md or CLAUDE.local.md
TDD is referenced in project memory
The user explicitly requests TDD methodology
The user asks to write tests or implement features
Use this skill for:
Implementing new features using TDD
Refactoring existing code with test protection
Fixing bugs with test-first approach
Ensuring code quality through TDD discipline
Validating that TDD principles are being followed
Do NOT use this skill for:
Pure design discussions without implementation
Documentation-only tasks
Research or exploration tasks
Core TDD Methodology
Test-Driven Development follows a strict three-phase cycle that must be repeated for every increment of functionality:
🔴 Red Phase: Write a Failing Test
Always write the test before any production code.
Write a test that expresses the desired behavior
Run the test and verify it fails (for the right reason)
Confirm the failure message indicates what's missing
:
Red Phase Principles
Test must be simple and focused on one behavior
Test name should clearly describe expected behavior
Test should be readable without looking at implementation
Failure should be meaningful and guide implementation
Example Flow:
1. Write: test_should_calculate_total_with_tax()
2. Run: Test fails - "ShoppingCart has no attribute 'calculate_total'"
3. ✅ Ready for Green phase
🟢 Green Phase: Make the Test Pass
Write minimal code to make the failing test pass.
Implement the simplest code that makes the test pass
Run the test and verify it passes
Run all tests to ensure nothing broke
Green Phase Principles:
Write only enough code to pass the current test
Don't add features not required by tests
It's okay to use shortcuts (you'll refactor later)
Focus on making it work, not making it perfect
Example Flow:
1. Implement: def calculate_total(self, tax_rate): ...
2. Run: Test passes ✅
3. Run all: All tests pass ✅
4. ✅ Ready for Refactor phase
🔵 Refactor Phase: Improve the Code
Clean up code while maintaining passing tests.
Identify duplication, poor names, or structural issues
Refactor incrementally, running tests after each change
Verify all tests still pass
Repeat until code is clean
Refactor Phase Principles:
Never refactor with failing tests
Make small, safe changes
Run tests after each refactoring step
Improve both production code and test code
Apply design patterns and best practices
Example Flow:
1. Identify: Duplicated tax calculation logic
2. Extract: Move to _calculate_tax() method
3. Run tests: All pass ✅
4. Improve: Better variable names
5. Run tests: All pass ✅
6. ✅ Commit and move to next feature
TDD Workflow Integration
Before Starting Any Code Task
Step 1: Understand the Requirement
Break down the task into small, testable behaviors
Identify the simplest test case to start with
State which TDD phase you're entering (Red)
Step 2: Plan the Test
Describe what test you're about to write
Explain what behavior it will verify
Confirm test will fail before implementation
During Implementation
Always follow this sequence:
🔴 Red: Write failing test → Run → Verify failure
🟢 Green: Write minimal code → Run → Verify pass
🔵 Refactor: Improve code → Run → Verify still passes
Commit: Save working, tested, clean code
Repeat: Next test for next behavior
Never skip phases or reverse the order.
Communicating TDD Progress
In every response involving code changes, explicitly state:
Current phase: Which phase you're in (Red/Green/Refactor)
Test status: Whether tests are passing or failing
Next steps: What comes next in the cycle
Example Communication:
🔴 RED PHASE: Writing a test for calculating order total with discounts.
Test: test_should_apply_percentage_discount_to_order_total()
Expected to fail because Order.apply_discount() doesn't exist yet.
[Test code here]
Running test... ❌ Fails as expected: "Order has no attribute 'apply_discount'"
🟢 GREEN PHASE: Implementing minimal code to pass the test...
[Implementation code here]
Running test... ✅ Passes!
Running all tests... ✅ All pass!
🔵 REFACTOR PHASE: Improving the discount calculation structure...
[Refactored code here]
Running all tests... ✅ All pass!
Ready to commit this increment.
Bundled Tools and Resources
Scripts
check_tdd_compliance.py
Analyzes code to detect TDD compliance issues and code smells that indicate test-after development.
Low-severity smells (magic numbers, long parameter lists)
Detection strategies and refactoring guidance
When to reference: When analyzing code quality or identifying non-TDD patterns.
Grep patterns for searching:
Nested conditionals: if.*:\s*\n\s+if
Long methods: Count lines between function definitions
Type checking: isinstance\(|typeof
God classes: Count methods per class
testing-patterns.md
Language-agnostic testing patterns and best practices:
Test structure patterns (AAA, Given-When-Then)
Test organization (fixtures, builders, object mothers)
Assertion patterns
Test doubles (stubs, mocks, fakes)
Parameterized testing
Exception testing
Test naming conventions
When to reference: When writing tests or improving test structure.
Assets
Hook Templates
Located in assets/hook-templates/:
pre-commit.sh: Git hook that runs TDD compliance checks before allowing commits
user-prompt-submit.sh: Claude Code hook that injects TDD reminders before every user prompt
These templates are used by setup_hooks.sh and can be customized for specific project needs.
Further reference
See references/tdd-reference.md for prompt-based validation and setup, TDD enforcement rules, common scenarios, workflow integration, troubleshooting, and summary.
