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.

1. Write a test that expresses the desired behavior
2. Run the test and verify it fails (for the right reason)
3. 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.

1. Implement the simplest code that makes the test pass
2. Run the test and verify it passes
3. 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.

1. Identify duplication, poor names, or structural issues
2. Refactor incrementally, running tests after each change
3. Verify all tests still pass
4. 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:

1. 🔴 Red: Write failing test → Run → Verify failure
2. 🟢 Green: Write minimal code → Run → Verify pass
3. 🔵 Refactor: Improve code → Run → Verify still passes
4. Commit: Save working, tested, clean code
5. 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.

Usage:

python scripts/check_tdd_compliance.py <path-to-code>

What it checks:

• Nested conditionals (sign of poor TDD structure)
• Long methods (TDD produces small, focused methods)
• Complex boolean conditions (TDD encourages extraction)
• Missing abstractions (type checking vs polymorphism)
• Test coverage (presence of corresponding test files)

When to use:

• After completing a feature or module
• Before committing code
• When reviewing code quality
• During refactoring sessions

validate_tests.py

Validates that tests exist, are properly structured, and follow TDD patterns.

Usage:

python scripts/validate_tests.py <path-to-tests>

What it checks:

• Test file existence and structure
• Test case count and naming
• Arrange-Act-Assert pattern adherence
• Test size and complexity
• Descriptive test names

When to use:

• Before committing new tests
• When validating test quality
• During code review
• After writing a batch of tests

setup_hooks.sh

Installs git hooks and Claude Code hooks to enforce TDD methodology automatically.

Usage:

bash scripts/setup_hooks.sh <project-directory>

What it installs:

• Git pre-commit hook: Validates TDD compliance before commits
• Claude user-prompt-submit hook: Injects TDD reminders into every interaction
• Updates CLAUDE.md to document TDD requirement

When to use:

• Once at project initialization
• When onboarding new team members to TDD
• When setting up TDD enforcement for the first time

References

Load these references when deeper understanding is needed:

tdd-principles.md

Comprehensive guide to TDD methodology including:

• The Red-Green-Refactor cycle in detail
• TDD philosophy and benefits
• Best practices and common mistakes
• TDD in different contexts (unit, integration, acceptance)
• Measuring TDD effectiveness

When to reference: When explaining TDD concepts or resolving questions about methodology.

code-smells.md

Catalog of code smells that indicate test-after development:

• High-severity smells (nested conditionals, long methods, god objects)
• Medium-severity smells (type checking, duplication, primitive obsession)
• 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.