Advisor Tdd Champion

Guides development teams through test-driven development practices with red-green-refactor discipline and testing strategy design.

When to Use This Agent

Choose this agent when you need to:

• Adopt TDD methodology on a project with guidance on writing failing tests first, then minimal implementations, then refactoring
• Design a testing strategy that balances unit, integration, and end-to-end tests according to the testing pyramid
• Improve existing test suites by identifying coverage gaps, flaky tests, over-mocking, and test coupling patterns

Consider alternatives when:

• You need to generate production code without test-first methodology and prefer a general-purpose coding assistant
• Your focus is on performance testing or load testing, which requires specialized benchmarking tools rather than TDD practices

Quick Start

Configuration

Copy
name: advisor-tdd-champion
type: agent
category: security

Example Invocation

Copy
claude agent:invoke advisor-tdd-champion "Guide me through TDD for implementing a shopping cart discount engine"

Example Output

TDD Cycle: Shopping Cart Discount Engine

--- RED Phase ---
Test: "applies 10% discount when cart total exceeds $100"
  Expected: applyDiscount({items: [{price: 60}, {price: 50}]}) => 99.00
  Status: FAILING (applyDiscount not yet defined)

--- GREEN Phase ---
Implementation (minimal):
  function applyDiscount(cart) {
    const total = cart.items.reduce((s, i) => s + i.price, 0);
    return total > 100 ? total * 0.9 : total;
  }
  Status: PASSING

--- REFACTOR Phase ---
  - Extract threshold and rate into named constants
  - Separate total calculation from discount logic
  - Add type annotations for cart parameter
  Status: ALL TESTS STILL PASSING

Next cycle: "stacks percentage and fixed-amount discounts correctly"

Core Concepts

TDD Methodology Overview

Aspect	Details
Red Phase	Write a single failing test that describes expected behavior before any production code exists
Green Phase	Write the minimal implementation that makes the failing test pass without gold-plating
Refactor Phase	Improve code structure, naming, and design while all tests remain green
Testing Pyramid	Many fast unit tests, fewer integration tests, minimal end-to-end tests for critical paths
Test Doubles	Stubs return predetermined data, mocks verify interactions, fakes provide working simplified implementations

TDD Cycle Architecture

       ┌──────────────────────────────────┐
       │          RED                      │
       │  Write ONE failing test           │
       │  that defines desired behavior    │
       └──────────────┬───────────────────┘
                      │
                      v
       ┌──────────────────────────────────┐
       │          GREEN                    │
       │  Write MINIMAL code to pass       │
       │  Resist urge to over-engineer     │
       └──────────────┬───────────────────┘
                      │
                      v
       ┌──────────────────────────────────┐
       │          REFACTOR                 │
       │  Improve structure, remove        │
       │  duplication, clarify naming      │
       │  ALL TESTS MUST STAY GREEN        │
       └──────────────┬───────────────────┘
                      │
                      └────> repeat

Configuration

Parameter	Type	Default	Description
testFramework	string	"auto"	Preferred testing framework: jest, pytest, rspec, junit, xunit, or auto-detect
cycleGranularity	string	"fine"	TDD cycle size: fine (one assertion per cycle) or coarse (one behavior per cycle)
coverageTarget	number	80	Minimum code coverage percentage to recommend as a project target
mockingStrategy	string	"minimal"	Approach to test doubles: minimal (prefer real), moderate, or comprehensive mocking
refactorPatterns	boolean	true	Suggest specific refactoring patterns (extract method, introduce parameter object, etc.)

Best Practices

1. Write the Assertion Before the Arrangement - Start each test by writing the assertion line that declares what the code should do, then work backward to construct the setup and invocation. This assertion-first approach forces you to think about outcomes rather than implementation details, producing tests that document behavior rather than mirror code structure.

2. Keep the Green Phase Ruthlessly Minimal - The temptation to write "good" code during the green phase undermines TDD's feedback loop. Write the simplest, even ugly, code that passes the test. The refactor phase exists specifically for design improvement, and attempting both simultaneously weakens both the design signal from failing tests and the safety net of passing tests.

3. Treat Tests as First-Class Documentation - Test names should read as behavioral specifications: "rejects_order_when_inventory_insufficient" communicates intent that survives long after the original developer leaves. Invest in descriptive naming, clear arrangement-act-assertion structure, and meaningful failure messages that tell the next developer exactly what contract was violated.

4. Refactor Test Code With the Same Rigor as Production Code - Test suites accumulate duplication, unclear naming, and tangled setup just like production code. Extract shared fixtures, use builder patterns for complex test data, and eliminate copy-paste test methods. Neglected test code becomes brittle and expensive, eventually causing teams to abandon TDD rather than maintain deteriorating test suites.

5. Align Test Distribution With the Testing Pyramid - Inverting the pyramid by writing more end-to-end tests than unit tests creates slow, flaky, and expensive feedback loops. Unit tests should cover the majority of logic branches, integration tests verify boundary interactions, and end-to-end tests confirm only critical user journeys. Each layer validates what layers below it cannot.

Common Issues

1. Tests Coupled to Implementation Details - Tests that assert on internal method calls, private state, or execution order break whenever code is refactored, even when behavior is preserved. Test observable outputs and side effects rather than internal mechanics. If renaming a private method breaks ten tests, those tests are verifying structure instead of behavior.

2. Flaky Tests Eroding Team Confidence - Tests that intermittently fail due to timing dependencies, shared state, or external service calls teach developers to ignore failures and retry builds. Isolate each test with fresh state, mock external dependencies at integration boundaries, and use deterministic time providers instead of real clocks in time-sensitive logic.

3. Skipping the Refactor Phase Under Deadline Pressure - Teams that practice only red-green without refactoring accumulate design debt inside a passing test suite. The code works but becomes increasingly difficult to extend. Schedule refactoring as an explicit part of each TDD cycle, not as a separate future activity that perpetually gets deprioritized.