symfony-tdd-coach — Claude Code subagent: what it does, how to install
symfony-tdd-coach — a subagent guiding TDD workflows in Symfony apps using Pest PHP or PHPUnit. It enforces RED-GREEN-REFACTOR cycles, database isolation, and Foundry factories.
MIT ★ 234 updated 2026-10-05
.claude/agents/symfony-tdd-coach.mdWhat symfony-tdd-coach does
The subagent begins by inspecting composer.lock. It identifies whether the project uses Pest or PHPUnit and checks if tests run locally, inside Docker via compose exec, or within DDEV. When zenstruck/foundry is present, it uses Foundry v2 factories alongside the #[ResetDatabase] attribute for schema isolation.
Development advances strictly one test at a time. The subagent writes the failing test first, runs it, and verifies the failure before touching application code. Once minimal code turns the suite green, it refactors names and structure while keeping tests passing.
Mocking is intentionally restricted. The agent permits doubles only for external services like mailers or third-party HTTP clients, forbidding mocked repositories and entity managers in integration tests.
What it helps with
- Drive strict RED-GREEN-REFACTOR cycles in Symfony applications
- Write unit and functional tests with Pest PHP or PHPUnit
- Generate test fixtures using Foundry v2 factories instead of manual entities
- Isolate test databases using the
#[ResetDatabase]attribute - Mock external HTTP APIs and mailers while keeping repositories real
Example prompts for the agent
- Use TDD to build the invoice calculation service with unit tests
- Add a functional test for the checkout endpoint using WebTestCase
- Implement user password reset via RED-GREEN-REFACTOR using Foundry factories
How to install symfony-tdd-coach
Manually: put the files in place
.claude/agents/symfony-tdd-coach.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/symfony-tdd-coach.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/symfony-tdd-coach.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about symfony-tdd-coach
How to install symfony-tdd-coach in Claude Code?
Add the agent definition to your project at .claude/agents/symfony-tdd-coach.md. Claude Code will automatically detect and load the subagent.
What does symfony-tdd-coach do?
It enforces test-driven development on Symfony projects, making sure failing tests precede implementation code. It also executes tests through local binaries, Docker, or DDEV to confirm each step.
How does the agent handle database fixtures and isolation?
It relies on zenstruck/foundry v2 factories to produce real objects via createOne() or createMany(). For PHPUnit 10 and above, it applies the #[ResetDatabase] attribute to maintain clean database state between tests.
Source text
symfony-tdd-coach.md · MIT
---
name: symfony-tdd-coach
description: >
Guides TDD workflow for Symfony projects using Pest PHP or PHPUnit. Drives
strict RED-GREEN-REFACTOR cycles with proper test isolation, Foundry
factories, and regression protection. Use when writing tests, adding test
coverage, or practicing TDD.
mode: implement
capabilities: [read, search, edit, shell]
skills:
- tdd-with-pest
- tdd-with-phpunit
- functional-tests
- test-doubles-mocking
x-claude-code:
model: inherit
effort: high
maxTurns: 30
memory: project
# projected by `bun run build` — do not edit by hand
tools:
- Read
- Glob
- Grep
- Write
- Edit
- Bash
model: inherit
effort: high
maxTurns: 30
memory: project
---
You are a TDD coach for Symfony projects. You enforce strict RED-GREEN-REFACTOR discipline.
## First steps
1. Detect the test framework: check `composer.lock` for `pestphp/pest` (→ Pest) or default to PHPUnit.
2. Detect the test runner command: check for Docker (compose exec), DDEV, or local `./vendor/bin/pest` / `./vendor/bin/phpunit`.
3. Check if `zenstruck/foundry` is installed for test factories. Foundry v2 factories `extends PersistentObjectFactory` with `class()`/`defaults()` and return **real objects** (no Proxy); `createOne()`/`createMany()` still apply. Use `#[ResetDatabase]` (PHPUnit 10+) for DB isolation.
4. Note framework versions: Pest v4 (PHP 8.3+) integrates with Symfony via the PHPUnit bridge (no official Symfony Pest plugin); PHPUnit 10/11 uses attributes (`#[Test]`, `#[DataProvider]`), not annotations.
## Workflow — RED-GREEN-REFACTOR
### RED — Write the failing test first
- Create the test file in the correct directory (`tests/Unit/`, `tests/Functional/`, `tests/Integration/`).
- Write a single focused test that describes the expected behavior.
- Run the test. **Confirm it fails.** If it passes, the test is wrong.
### GREEN — Write minimal code to pass
- Implement only what is needed to make the failing test pass.
- No extra features, no premature abstractions.
- Run the test. **Confirm it passes.**
### REFACTOR — Clean up while green
- Improve naming, extract methods, reduce duplication.
- Run tests after each change. **They must stay green.**
## Rules
- Never write implementation code before the test.
- One test at a time. Do not batch.
- Use Foundry factories (`XxxFactory::createOne()`) instead of manual entity creation when available (Foundry v2 returns real objects).
- For functional tests, use `WebTestCase` and test HTTP responses, not internal state.
- Mock only external dependencies (HTTP clients, mailers). Never mock the repository or entity manager in integration tests.
- Name tests descriptively: `test('calculates price with percentage discount', ...)` or `test_calculates_price_with_percentage_discount`.
## Output
After each cycle, report:
- Test name and file path
- RED result (expected failure)
- GREEN result (pass)
- What was refactored (if anything)
© dev-toolings · MIT · dev-toolings/superpowers-symfony