Tdd

---
name: tdd
description: Use when the user asks for test-driven development, red-green-refactor, "write the test first", or wants a feature or bug fix built test-first — including mid-build when they ask to switch to test-first. Do NOT use when tests are a verification step after the build, the project has no suite and the user has not asked for one, the change is throwaway probe code, or the goal is restructuring without behaviour change (refactoring) or finding an unknown cause (root-cause).
---

# TDD

Red → green, one vertical slice at a time. Before the first test: agree seams (below). Then loop.

## Seams — agree before writing

A **seam** is a public boundary where behaviour is observable: exported function, HTTP route, CLI invocation. Tests live at seams, never in internals. List the seams under test and confirm them with the user (one `ask_user` call, recommended set marked). No test at an unagreed seam.

## The loop

1. **Red.** One failing test at an agreed seam for the next smallest real behaviour. Run it; confirm it fails for the right reason (assertion, not import/syntax error).
2. **Green.** Least code that passes. Run the test and the touched suite.
3. **Repeat.** The next test follows from what the last cycle taught. Never write all tests first, then all code.
4. **Refactor** only on green, as a separate step; rerun tests after.

## Test integrity (agent guard)

- **Tests are frozen during green.** Never edit, delete, skip, loosen, or `.only` a test to make it pass. If a test is wrong, stop, say why, and get agreement before changing it.
- Never special-case test inputs in production code (hard-coded returns for the test's literal).
- Before claiming done, `git diff` the test files; explain any change made during a green step.

## Test quality

- **Expected values from an outside source of truth** — a known literal, worked example, or the spec. Never recompute the expected value the way the code does.
- **Behaviour, not structure.** A test that breaks under a behaviour-preserving refactor is coupled to internals; rewrite it at the seam.
- **Mock only external boundaries** (network, clock, filesystem), and only when slow or stateful.
- **Name like a spec**: "user can check out with an empty cart".
- **Property tests for rules over many inputs** (parsers, round-trips, invariants) when the project already has a property library (fast-check, Hypothesis, proptest); otherwise a table of examples.
- **Optional strength check:** if a mutation tool is already installed (Stryker, mutmut, cargo-mutants), run it on the changed module; surviving mutants point to missing assertions. Do not install one unasked. Manual alternative: break one line of the new code, confirm a test goes red, revert.

Never claim a cycle green that you did not run.

## Scaling: one agent or several

Main thread only — the loop is sequential by design. Never parallelise red/green steps or let a child edit tests.

Sources (accessed 3 October 2026): https://code.claude.com/docs/en/best-practices (failing test before the fix); https://stryker-mutator.io/docs/ (killed vs surviving mutants); https://hypothesis.readthedocs.io/