TDD With AI: Test-First Development With Coding Agents

Bookly lets a client book a time slot. The first booking feature needs one rule: a second client cannot book a slot that is already taken. Write the test for that rule before the agent touches the booking code. This rule is the acceptance check no-double-booking in the acceptance.json file from Step 3. When the test passes, set that check's passes field to true.

1. 1. Ask for the red test

   Prompt the agent for one failing test. Then read the test before you run it. Each assertion must check a value that a client or the owner can see, such as the booking that exists after the second attempt.

2. 2. Read the failure

   The test must fail because the rule is missing, for example because the second booking succeeds. A typo or a missing import also makes a test fail, but that is the wrong reason. Fix the test and run it again until the failure shows the missing rule.

3. 3. Let the agent make it pass

   Use the GREEN prompt above. The agent changes the booking code and may not edit the test. Run the suite and confirm that the new test and the old tests pass.

4. 4. Refactor with the test in place

   Move the overlap check into a named function, and keep the test green. The data model decides whether a unique constraint in the database backs up the check. The planning page covers that model.

import { expect, test } from "vitest";
import { bookSlot } from "../src/lib/bookings";
import { fixtures } from "./test-data";

test("a second client cannot book a slot that is already taken", async () => {
  const { staffId, openSlot, alice, bob } = fixtures;
  await bookSlot({ staffId, startsAt: openSlot, clientId: alice.id });
  await expect(
    bookSlot({ staffId, startsAt: openSlot, clientId: bob.id })
  ).rejects.toThrow();
});

The test awaits the assertion. Vitest 5 fails a test whose async assertion is not awaited, so the await is part of the test, not a style choice.

• You write it. This gives the most control. Use it for the auth, payment and booking rules.
• The agent writes it, and you review each assertion. Replace any assertion that checks what the code does now with one that checks the rule.
• A separate test-writer subagent writes it. The implementer then starts in a fresh context. Part 3 shows how to stop the implementer from editing that test.

Agent-written tests often print values instead of asserting them. Read every assertion before you accept the red suite.

Claude Code has 33 hook events. Four of them shape a TDD gate. Exit code 2 has a different effect on each event, as the table shows.

Set up the Stop gate in four steps:

1. Save the script below as .claude/hooks/test-gate.sh and make it executable.
2. Add the Stop entry below to .claude/settings.json.
3. Run the script yourself with an empty first stop: echo '{}' | .claude/hooks/test-gate.sh. On a green suite it must exit 0. Break one test on purpose and run it again. It must exit 2.
4. Start a task in which the agent has to fix a failing test, and watch the hook send the failure back.

#!/usr/bin/env bash
# .claude/hooks/test-gate.sh (Stop hook, needs jq)
input=$(cat)
if echo "$input" | jq -e '.stop_hook_active == true' > /dev/null; then
  exit 0
fi
if ! output=$(npm test 2>&1); then
  echo "$output" >&2
  echo "The test suite is red. Fix the failing test, then finish." >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/test-gate.sh",
            "timeout": 600,
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

The script follows the docs: it reads stop_hook_active from the JSON input and exits 0 when it is true. That gives the agent one forced retry per stop. It is not an unbreakable gate. Claude Code overrides a Stop hook after it blocks eight times in a row with no tool call from Claude in between. An agent that keeps editing and re-running resets that count, so the hard gate for a red suite is CI plus a PreToolUse rule.

The script needs jq. onFailure set to block needs Claude Code v2.1.295 or later. With it, a crashed or timed-out gate, including a missing jq, blocks the stop instead of letting the agent finish.

1. The agent says the booking feature is finished.
2. The Stop hook runs npm test. The "no double booking" test fails.
3. The hook exits with code 2 and writes the failure to stderr. Claude Code sends that text back to the agent as the reason it cannot stop.
4. The agent gets another turn, changes the booking code, and tries to finish again.
5. The agent tries to stop a second time. This stop carries stop_hook_active set to true, so the hook exits 0 and the turn ends without a second test run.

These steps show how the gate behaves. They are not a measured result for Bookly. If the suite is still red at that point, the red test reaches CI. There the required check fails and blocks the merge, and the failing test name in the CI log shows the owner where to look.

Claude Code subagents are Markdown files in .claude/agents/ for a project, or ~/.claude/agents/ for every project. Each one starts with a fresh context window. Restrict its tools with tools or disallowedTools. A read-only reviewer looks like this:

---
name: test-reviewer
description: Reads new tests and reports weak assertions. Never edits files.
disallowedTools: Write, Edit
---
Review the tests named in the request. For each test, list assertions that
check truthiness, values copied from the implementation, or no assertion at all.

Bash can still write files, so disallowedTools: Write, Edit does not block every change. Add a PreToolUse hook that exits with code 2 for edits to test files, or a deny rule for the shell commands that write files.

Mutation score is the share of deliberately injected bugs that the tests catch. On a benchmark of real Python functions, LLM-written unit tests averaged a 40.21% mutation score across 3,909 function-level tasks.

Coverage does not catch this. Wang, Xu, Briand and Liu note that some test suites achieve 100% coverage but only a 4% mutation score. Their MUTGEN method puts mutation feedback into the prompt, and it beat EvoSuite and plain prompting on 204 subjects.

The three patterns to search for in agent-written tests:

• A mock that returns exactly what the test told it to return. The test checks its own setup.
• Truthiness checks such as expect(result).toBeTruthy() instead of specific values.
• Expected values copied from the current output, so the test confirms the bug.

Vitest 5.0 needs Vite 6.4.0 or later and Node.js 22.12.0 or later. These changes matter most when an agent writes the tests:

• Unawaited async assertions now fail the test. Before Vitest 5, they only printed a warning.
• clearMocks defaults to true.
• Browser Mode locators are strict by default. getByText('Item') no longer matches 'Item 1'.
• expect.poll rejects when it times out.
• New: vi.when, a --repeats flag for flaky tests, vitest doctor, and the Browser Mode Trace View.
• The authors report wall-clock gains of about 8% to 53% in their own benchmarks.

// Fails in Vitest 5: the async assertion is not awaited
test("saves the booking", () => {
  expect(saveBooking(input)).resolves.toMatchObject({ status: "confirmed" });
});

// Passes: await the async assertion
test("saves the booking", async () => {
  await expect(saveBooking(input)).resolves.toMatchObject({ status: "confirmed" });
});

Add the Vitest 5 release to the context file, so the agent writes awaited assertions from the start.

This guide gives no coverage percentage as a target. The published evidence points to mutation score, and the right number depends on the project. Use the steps below on the modules where a bug costs the most.

1. Run npx vitest run --coverage to find code that no test touches.
2. Run StrykerJS with its Vitest runner on the critical modules first: auth, payments and bookings.
3. Send each surviving mutant to the agent as the next failing test. Ask for a test that fails on that mutant and passes on the original code.
4. Run the suite again. Repeat until the surviving mutants on critical logic are removed or explained.

Install the Stryker Vitest runner with @stryker-mutator/vitest-runner. Stryker forces its coverage analysis to perTest and overrides several Vitest options, so read its Vitest notes before you add it to a hook.