When Claude writes code and tests together, the tests usually pass because they were written to match the code. This agent reverses the order so every test has been seen failing first, which suits rules where a quiet mistake is expensive: pricing, permissions, validation and parsing.
When to use the TDD Engineer agent
- Business rules such as pricing, discounts, tax or permissions
- Validators, parsers and data transformations with clear expected outputs
- Bug fixes where you want a test that would have caught the bug
- Code you will refactor later and need a safety net for
What is in the agent file
| Name | tdd-engineer |
|---|---|
| Tools | Read, Write, Edit, Grep, Glob, Bash. It can edit files and run commands, so review its diff. |
| Model | sonnet, up to 45 turns per task |
| Kit | Engineer kit, 107 lines |
How it works. Beyond its role statement, the file sets out 5 rules it follows: Slice ordering; Assertion quality; Bug fixes; Severity rubric; When to relax the loop.
What it reports. Every run ends in the same structure: Slices completed, Red evidence, Green evidence, Suite, Coverage notes, Limitations.
Excerpt from the agent file
The settings and opening instructions, as they appear in .claude/agents/tdd-engineer.md:
---
name: tdd-engineer
description: Implements behavior through a strict red-green-refactor loop, one small slice at a time, with assertions that fail for the right reason. Invoke by name for business logic, validators, parsers, pricing or permission rules, data transformations and bug fixes with clear expected outputs.
model: sonnet
maxTurns: 45
tools: Read, Write, Edit, Grep, Glob, Bash
---
You are a TDD Engineer. The loop's value is not discipline for its own sake: **a test you have watched fail, for the reason you expected, is the only test you know actually tests something.** Tests written after the code routinely pass against broken implementations, because they were written by someone who already believed it worked.
1. Pick one slice — one behavior, one case.
2. Write the test from the caller's perspective. Name it after the behavior.
3. **Run it. Watch it fail, and read the failure.** It must be the *assertion* failing — not a typo, a missing import, or a stack trace from the wrong place. If it fails for the wrong reason, the test is not testing what you think.
4. Write the least code that turns it green. Hardcoding is allowed and often correct; the next test forces the generalization.
5. Run the focused test. Green.
6. Refactor with the net in place. If a test goes red, you changed behavior — undo.
7. Next slice.
8. Periodically run the broader suite.The full file continues with the rules above and the exact report format. It is included in the Agentsforce kit.
Example requests
Name the agent to be sure Claude uses it, or describe the task and let its description trigger it:
- "Use tdd-engineer to implement the discount rules in pricing.md, one rule at a time."
- "Add a parser for this CSV format with TDD. Start with the empty file case."
- "Use tdd-engineer to fix the timezone bug: write the failing test first."
- "Build the permission check for team admins test-first and show me the red output."
When to use a different agent
| If you need | Use instead |
|---|---|
| UI layout and visual work | Use frontend-design |
| Exploratory prototypes where the behavior is not settled yet | The main session is faster; add tests once it settles |
| End-to-end browser tests | Use browser-qa-engineer |
Works well with
- Code Reviewer: checks what a change did, not whether a file looks fine
- Debugging Specialist: finds why a bug happens before changing code
- API Engineer: designs and changes endpoints that clients depend on
Related playbooks in the kit, which Claude loads when the task calls for them: red-green-refactor, test-strategy, test-fixtures-factories.
How to get it
- Write your own: the free Subagent Generator drafts a starter tdd engineer file you can edit and save in
.claude/agents/. - Use the tested version: Agentsforce includes this agent with 54 other specialists and 89 playbooks for a one-time $49, installed with one command.
Frequently asked questions
Can Claude Code do test-driven development?
Yes, if you make it follow the loop. This agent writes one failing test, shows the failure output, writes the minimum code to pass, then refactors, and reports the red and green evidence for each slice.
Does it work with any test framework?
It uses whatever the project already runs, such as Jest, Vitest, pytest or PHPUnit. It reads the existing tests first and matches their style.
When does it skip the strict loop?
Strict TDD fits logic with known expected outputs, not exploratory work or UI layout. For those its rule is to spike freely, then delete the spike and rebuild test-first, and to say why in its report whenever it skips the failing-test step.