TDD Red Strategist

A test-driven development agent focused on the Red phase: writing clear, specific failing tests that describe desired behavior from requirements before any implementation exists. Works with a Green phase agent that writes the implementation.

When to Use This Agent

Choose TDD Red Strategist when:

• Starting a new feature that should be developed with TDD
• Writing acceptance tests from GitHub issue requirements
• Defining behavior through tests before implementation
• Adding test coverage for edge cases and error conditions
• Practicing disciplined TDD with clear Red → Green → Refactor phases

Consider alternatives when:

• Implementation code already exists and needs tests (use a test writing agent)
• Making failing tests pass (use the TDD Green agent)
• Writing integration or E2E tests for existing systems (use a test automation agent)

Quick Start

Copy
# .claude/agents/tdd-red-strategist.yml
name: TDD Red Strategist
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are in the TDD Red phase. Write clear, specific FAILING tests
  that describe desired behavior. Tests must fail because the
  implementation doesn't exist yet, not because of errors.
  Extract requirements from GitHub issues. Each test should
  describe one specific behavior.

Example invocation:

Copy
claude --agent tdd-red-strategist "Write failing tests for the
  user login feature described in issue #42. Cover happy path,
  invalid credentials, account lockout after 5 attempts, and
  rate limiting."

Core Concepts

Red Phase Rules

1. Read the requirements (GitHub issue, user story)
2. Identify distinct behaviors to test
3. Write ONE test at a time
4. Run the test — it MUST fail
5. Verify it fails for the RIGHT reason
   (missing function, not syntax error)
6. Move to the next behavior
7. When key behaviors are covered → hand off to Green phase

Test Design Principles

Principle	Description	Example
One assertion per test	Test one specific behavior	test_login_returns_token
Descriptive names	Name describes the behavior	test_login_with_invalid_email_returns_401
Arrange-Act-Assert	Clear test structure	Setup → Execute → Verify
Independent tests	No shared state between tests	Each test creates its own data
Test behavior, not implementation	Assert outcomes, not internals	Check return value, not method calls

Test Priority Order

1. Happy path — the main success scenario
2. Input validation — invalid/missing inputs
3. Edge cases — boundary conditions
4. Error handling — failure scenarios
5. Security — unauthorized access, injection
6. Performance — timeout, large inputs (if relevant)

Test Template

Copy
def test_[action]_[condition]_[expected_result]():
    """
    Given [precondition/context]
    When [action is performed]
    Then [expected outcome]
    """
    # Arrange
    user = create_test_user(email="[email protected]")

    # Act
    result = login(email="[email protected]", password="correct")

    # Assert
    assert result.status == 200
    assert result.token is not None

Configuration

Parameter	Description	Default
test_framework	Testing framework to use	pytest / jest
test_directory	Where to write test files	tests/
naming_convention	Test naming pattern	test_action_condition_result
issue_source	Where to find requirements	GitHub issues
coverage_depth	How many scenarios to cover	Core + edge cases
mock_strategy	How to handle external dependencies	Dependency injection

Best Practices

1. Write the test name before the test body. The test name should read like a specification: test_login_with_expired_token_returns_401_and_refresh_prompt. If you can't name the test clearly, you don't understand the behavior well enough to test it. A good test suite's names read like a feature specification that anyone can understand.

2. Verify the test fails for the right reason. A test that fails because of an import error or syntax mistake isn't a useful Red test. It should fail because the function returns the wrong value, raises the wrong exception, or doesn't exist yet. Run the test and check the failure message. "AssertionError: expected 200, got None" is a good failure. "ModuleNotFoundError" needs fixing.

3. Start with the simplest happy path test. Don't begin with edge cases. Write a test for the most basic successful scenario first. This test drives the initial implementation. Once the happy path works (Green phase), come back and add tests for invalid inputs, edge cases, and error conditions. This incremental approach builds the feature systematically.

4. Use Given-When-Then comments to document intent. Add a docstring or comment to each test explaining the precondition (Given), the action (When), and the expected outcome (Then). This documentation helps the Green phase developer understand what behavior the test demands. It also serves as living documentation for anyone reading the test suite later.

5. Keep tests independent of implementation details. Test what the code does, not how it does it. Assert on return values, state changes, and side effects, not on which internal methods were called or in what order. Implementation-coupled tests break during refactoring even when behavior is preserved, which is the opposite of what tests should do.

Common Issues

Tests are too coupled to a specific implementation approach. If your test mocks internal methods or asserts on implementation details, it constrains the Green phase to one approach. Instead, test the public interface: inputs and outputs. If the function should return a user object, assert on the object's properties, not on which database query produced it.

Too many tests written before any implementation. Writing 20 tests before implementing anything creates overwhelming pressure during the Green phase. Write 3-5 tests covering the core behavior, hand off to Green, then add more tests in the next Red phase. Small Red-Green cycles keep momentum and provide frequent validation that the approach is working.

Tests require infrastructure that doesn't exist yet. If testing a database query, you need a test database. If testing an API call, you need a mock server. Set up test infrastructure (fixtures, mocks, test databases) as part of the Red phase before writing tests that depend on it. Otherwise, tests fail for infrastructure reasons rather than missing implementation, muddying the signal.