Test Driven Development With AI Agents: A Step-by-Step Guide

· 10 min read

Test driven development with AI agents works when you split the roles cleanly: you write or approve the failing tests, and the agent writes only the implementation that makes them pass. Without that split, the agent writes the code and the tests that bless it, and a green suite tells you very little. The rest of this guide is the workflow I recommend, with the guardrails that keep the agent honest.

Key takeaways- Humans own the tests; the agent owns the implementation. Once the agent can edit both, a passing suite stops being evidence.- Commit the red tests first, then enforce "do not touch tests/" mechanically with CODEOWNERS, a pre-commit hook or a read-only path, not just a line in a prompt.- Work one failing test at a time, feed back raw failure output, and stop after three failed attempts to re-check the test and the spec.- Mutation testing and property-based tests are optional but catch what hand-picked examples miss, because agents overfit to visible examples.- Review the diff for edited tests, new skip markers, hard-coded expected values and swallowed exceptions before you merge.

The direct answer: you own the tests, the agent owns the code

The practice is old; the roles are what change. Test-driven development means you define the test cases and expected results first, then build the software with the sole purpose of passing them, as Kane Simms describes it. With an agent, the point is who holds the pen. You hold it for tests, the agent holds it for code.

Tests become the prompt

Prose is ambiguous. "Handle duplicate requests gracefully" can mean five different behaviors, and an agent will pick one that looks plausible. A test that sends the same request twice and asserts exactly one record exists leaves no room for that guess. It is also cheap to re-run after every agent edit.

Writing tests first is also an exercise in defining requirements. Simms makes that point about the traditional approach too: tests written after the code assume the code already contains every needed requirement. An agent amplifies that flaw, because it produces code fast and confidently.

Why the agent's passing signal needs a human behind it

A mabl post from February 2026 argues that in agentic workflows a passing test is a decision input to an autonomous system, not only a signal to a human. The agent uses it to decide whether to retry or move on. That is a vendor's framing, and it proves nothing by itself. It does match the mechanism: if the test is wrong, the agent will faithfully optimize for the wrong thing.

When not to use it

Skip this for throwaway scripts, exploratory UI work and spikes where the requirement is still unknown. You cannot write a meaningful failing test for something you cannot yet describe. For a spike, let the agent explore freely, then throw the code away and write the tests for the version you keep.

Practical rule: If you cannot state the expected behavior in an assertion, you are not ready to hand the task to an agent under TDD.

Prerequisites

You need four things in place before the loop is worth running.

  • An agent that edits files and runs commands. Claude Code, Cursor agent mode or similar. It must be able to run your test command itself, or you become the feedback loop.
  • A git repo with a clean working tree. The red-tests commit is your rollback point, and a dirty tree muddies it.
  • A fast single-command test runner. pytest, Jest or Vitest, or go test. I aim for an unsuite under 30 seconds for the unit suite, because the agent will run it dozens of times per task. That figure is my working target, not a researched threshold.
  • CI, a coverage or mutation tool and a rules file. CI should run the same command the agent runs. Use coverage.py, Stryker or Go's -cover. The rules file is whatever your agent reads at start, such as a project instructions file.

The honest limitation: flaky suites

If your existing suite is flaky, fix that first. An agent cannot tell a flaky failure from a real one. It will "fix" working code to chase a random failure, or conclude that a real failure is noise. Quarantine or repair flaky tests before you start, or scope the agent to a module whose tests are deterministic.

Step 1: Write the behavior spec in plain language

Write five to ten bullets. Cover inputs, outputs, edge cases and explicit non-goals. Non-goals matter most: they stop the agent from inventing features that nobody asked for and nobody will review.

Name the failure modes

Agents tend to implement the happy path and stop. List the unhappy paths yourself: empty input, auth failure, duplicate requests, timeouts. Simms makes a similar point for building agents: you have to decide in advance what happens when a tool call fails or an API doesn't work. The same discipline applies when an agent is writing your code.

One behavior per task

Keep each task to a single behavior. Small slices keep diffs reviewable and failures attributable. If a task touches three behaviors and one test breaks, you will not know which change caused it.

Example spec (illustrative): "Function normalize_email(raw) returns lowercase, trimmed text. Empty string raises ValueError. Plus-addressing is preserved. Non-goal: no DNS or MX validation."

Step 2: Get failing tests written, and review them yourself

Let the agent draft tests from the spec. Then read every assertion. A test that asserts the wrong thing is worse than no test, because it creates confidence you have not earned.

Confirm they fail for the right reason

Run the tests. A red result is not enough; read the message. You want "function not defined" or "expected X, got Y". You do not want an import typo, a syntax error or a missing fixture. A test that fails for the wrong reason may pass for the wrong reason later.

Reject tautologies and over-mocking

Watch for two patterns:

  • Tests that mock the unit under test, so the assertion checks the mock.
  • Tests that only assert a mock was called, which says nothing about the result.

Both pass whatever the code does. If a test would pass with the function body replaced by pass, delete it.

Practical rule: Read every assertion, and demand that each test fails for a reason you can name before any implementation exists.

Step 3: Lock the tests, then let the agent implement

Commit the red tests first. That commit is your baseline and your rollback point.

Say it in the rules file

Add explicit instructions: do not edit files under tests/, do not skip, xfail or delete tests, and run the single test command after each change. Explaining the reason in the file helps the agent follow it in spirit, not only in letter.

Enforce it mechanically

Instructions are polite; enforcement is reliable. Use a CODEOWNERS rule that requires your review for test paths, a pre-commit hook that rejects staged changes under tests/, or a read-only filesystem path for test files. Which one fits depends on your setup. CODEOWNERS only bites at pull request time. A hook can be bypassed locally with --no-verify, so back it with CI.

To test the lock, ask the agent to change one test file and confirm the hook or rule blocks it. If it does not, you have a prompt, not a control.

Step 4: Run the red-green loop in small increments

Laptop terminal with red and green test results beside a hand-drawn loop diagram on paper
Laptop terminal with red and green test results beside a hand-drawn loop diagram on paper

Ask for the minimum code that passes one failing test at a time. Large leaps tend to produce plausible code that passes by special-casing inputs, such as returning the exact value the test expects.

Feed back raw output

Paste the raw failure output, not your paraphrase. Stack traces carry file names, line numbers and actual values. Your summary drops exactly the details the agent needs.

Cap iterations

If three attempts fail, stop. Re-read the test and the spec, then decide which is wrong: the test, the spec or the prompt. A fourth blind attempt usually produces a workaround. The three-attempt cap is a rule of thumb I use, not a measured optimum.

Example (illustrative): the agent has failed test_rejects_empty_string three times. You read the test and find it expects ValueError, while the spec bullet said TypeError. Fix the spec, fix the test, commit that change yourself, and restart the loop.

Practical rule: One failing test, raw output in, three attempts out. Then think instead of retrying.

Step 5: Refactor under green, and add property or mutation checks (Optional)

Once everything is green, ask for a refactor with one condition: the suite stays unchanged and passing. Run it after each change. If the agent proposes touching tests during a refactor, that is a signal the behavior changed.

Mutation testing

A mutation tool changes your code in small ways and checks whether any test notices. Surviving mutants show assertions too weak to catch real bugs. Run it on the changed module only, since full runs can be slow. Stryker covers JavaScript and TypeScript. For Python and Go, check which tool fits your stack in its own documentation.

Property-based tests

For pure logic, add property-based tests with Hypothesis or fast-check. Hand-picked examples let an agent overfit: it can satisfy five examples with a lookup table. A property such as "normalizing twice equals normalizing once" generates inputs the agent never saw. This step is optional and fits pure functions best; it adds little for glue code.

Verify the result and roll back safely

Passing tests are the start of verification, not the end. Check the diff for these:

  • Any change under tests/.
  • New skip, xfail or commented-out assertions.
  • Hard-coded expected values inside the implementation.
  • Broad try/except blocks that swallow errors.

Then run the full suite and CI from a clean checkout. Local passes can hide missing files and environment assumptions. I cover the broader checklist in how to review AI generated code.

Know what the tests cannot tell you

Evaluations themselves can be weak. A September 2026 report on a review of over 440 AI benchmarks, covered by Smart Reel Agency, says most had limitations in at least one domain. That concerns model benchmarks, not your unit tests. It is a clue, not proof, that a green score can mislead, and your suite deserves the same skepticism.

Roll back

Use git reset to the red-tests commit, or revert the single implementation commit. Keep one agent task per branch so reverting stays trivial. If the agent also touched unrelated files, that is a sign the task was too large.

Practical rule: Treat green as a claim to check, and keep every agent task on its own branch so you can discard it.

Set this week's publishing plan

Turn this into a first run on a real but small piece of work.

  1. Pick one low-risk module with a deterministic, fast test suite, and confirm one command runs it.
  2. Add three lines to your agent rules file: no edits under tests/, no skip or xfail, run the test command after each change.
  3. Add a CODEOWNERS rule or pre-commit hook for the test path, and prove it blocks a test edit.
  4. Write a five-to-ten bullet spec for one behavior, including non-goals and two failure modes, then have the agent draft tests and review every assertion.
  5. Commit the red tests, then run the loop with a three-attempt cap per failing test.
  6. Review the diff against the checklist, run CI from a clean checkout, and note which review items caught something.
  7. Write up what you would change, and read my AI-driven development notes or the account of how I rebuilt an open source package with Cursor and Claude for related workflows. If you are starting a new SaaS and want the auth and billing groundwork done, MakeV1: Ship your SaaS with the hard parts already done. is one place to start.
Test Driven Development With AI Agents: A Step-by-Step Guide - Ali Hesari