TDD Green Agent

A test-driven development agent focused on the Green phase: writing the minimal code necessary to make failing tests pass. Works in conjunction with a Red phase agent that writes the tests, ensuring implementations satisfy requirements without over-engineering.

When to Use This Agent

Choose TDD Green Agent when:

• Failing tests exist and need minimal implementation code to pass
• Working in a TDD workflow after the Red phase (tests written)
• Implementing features driven by acceptance criteria from GitHub issues
• Writing production code that satisfies test expectations precisely
• Practicing disciplined TDD with clear Red → Green → Refactor phases

Consider alternatives when:

• Writing tests before implementation (use the TDD Red agent)
• Refactoring passing code for cleanliness (use a refactoring agent)
• Building features without existing test coverage (use a general dev agent)

Quick Start

Copy
# .claude/agents/tdd-green-agent.yml
name: TDD Green Agent
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are in the TDD Green phase. Write the MINIMAL code to make
  failing tests pass. Do not write more than required. Do not
  refactor. Do not add features not covered by tests. When all
  tests pass, stop. The code can be ugly — that's what the
  Refactor phase is for.

Example invocation:

Copy
claude --agent tdd-green-agent "Make the failing tests in
  tests/auth/test_login.py pass. Check the test expectations
  carefully and implement only what's needed."

Core Concepts

Green Phase Rules

1. Read the failing test(s)
2. Understand what the test expects
3. Write the SIMPLEST code that makes it pass
4. Run the test — does it pass?
   Yes → Move to next failing test
   No  → Fix until it passes
5. All tests pass → STOP (do not refactor yet)

Implementation Hierarchy

Approach	When to Use	Example
Return constant	Test expects specific value	return 42
Simple conditional	Two test cases	if x > 0: return "positive"
Actual algorithm	Multiple test cases require it	Implement the logic
Minimal class/function	Test imports a new module	Create with required methods only

Code Quality in Green Phase

Acceptable in Green Phase:
  ✓ Hardcoded values that pass tests
  ✓ Duplicate code between functions
  ✓ Long functions without extraction
  ✓ Missing error handling (if not tested)
  ✓ Naive algorithms (O(n²) is fine if tests pass)

NOT Acceptable (that's for Refactor phase):
  ✗ Adding untested features
  ✗ Optimizing performance
  ✗ Extracting helper functions
  ✗ Adding error handling not required by tests
  ✗ Writing additional tests

Configuration

Parameter	Description	Default
test_command	Command to run tests	pytest / npm test
test_filter	Filter for specific failing tests	All failing
minimal_mode	Enforce minimal implementation	true
allow_refactor	Allow refactoring during Green	false
verify_all_pass	Run full test suite after changes	true
issue_reference	GitHub issue for context	From branch name

Best Practices

1. Read the test assertion first, then the setup. Understanding what the test expects (the assertion) tells you what your code needs to produce. The setup tells you what inputs to handle. This order prevents building the wrong mental model. If the test asserts result == 42, your first implementation can literally be return 42. Add complexity only when more tests demand it.

2. Make one test pass at a time. Don't try to make all failing tests pass simultaneously. Pick the simplest failing test, make it pass, run the suite, then move to the next. This incremental approach prevents debugging multiple implementation issues at once and keeps your changes small and focused.

3. Resist the urge to write "proper" code. The Green phase intentionally produces ugly, minimal code. This feels wrong, but it's the point. Writing elegant code now means you're implementing features your tests don't verify. The Refactor phase (coming next) is where you clean up. Trust the process: passing tests come first, clean code comes second.

4. Don't add error handling unless a test requires it. If no test checks what happens with invalid input, don't write validation code. Untested error handling gives false confidence and often implements the wrong behavior. Write a test for the error case (in the next Red phase), then add the handling. This ensures every code path is tested.

5. Verify no existing tests broke after your implementation. Run the full test suite, not just the previously failing tests. Your minimal implementation might accidentally break something else. If it does, fix only the breakage without changing the approach—unless the breakage reveals a genuine conflict that requires reconsidering the implementation.

Common Issues

Implementation makes the target test pass but breaks other tests. This usually means the new code changes shared state or violates an assumption other tests rely on. Check whether the broken tests share fixtures, global variables, or database state with the new test. Fix by isolating the change: use function parameters instead of globals, create separate test fixtures, or scope the change more narrowly.

The simplest implementation feels like cheating. Returning a hardcoded constant or using a simple conditional feels wrong when you "know" the real algorithm. But TDD's power comes from this discipline: the test suite defines the requirements, and you implement exactly those requirements. More tests will force the implementation to evolve naturally. Trust that the Red phase will add the tests that require the real algorithm.

Multiple failing tests require conflicting implementations. This rare situation means either the tests are wrong or the design needs rethinking. Don't try to satisfy contradictory tests with clever code. Instead, go back to the Red phase: verify the tests are correct, resolve the contradiction, and return to Green with a clear target.