TDD with Claude Code: Write the API Test First
TDD with Claude Code works best when the first test hits the API. Write it red, let the agent make it green, then refactor with the flows as a guard.

TDD with Claude Code works when the first test hits the API and the agent cannot change it to get a pass. Write the test so it fails, ask the agent to make it pass, then refactor while the same test keeps running. Stresseur flows are files in your repo, named *.yamlflow.yaml. An agent runs one with npx stresseur flow run. The loop is the same in Cursor. This post gives the steps, a measured example from one app, and what to do when the agent reaches for the assertion.
The loop: red, green, refactor with an agent
The loop has five steps. The post on giving agents API tests covers the setup in full, and this post covers the order of work.
- Describe the new behavior as a change to an API test, before any code changes.
- Run the test and watch it fail at the step you expected. That is red.
- Ask the agent to change the code until the test passes. That is green.
- Refactor, with the test running after every edit.
- Run the whole suite before you push.
The test sits at the API because the agent needs a check it can run after every change. To run that check on every pull request the agent opens, see Claude Code GitHub Actions.
Why test first matters more with an agent
An agent can edit a route, a handler and a migration in one go, and it then needs to know whether the checkout flow still works. A test written after the change tends to describe what the code already does, so it passes. A test written first describes what you asked for, so it fails until the code is right. The same reasoning drives AI code testing in general, where the check has to run after every change the agent makes.
There is a second reason. An agent that is told to make the tests pass can make them pass by making them weak. Writing the test first, and treating it as fixed while the agent works, closes that route. If the agent wants the test changed, that is a change in the requirement, and you decide it. The wider pattern of agents writing and running API tests is the subject of Agentic Testing for APIs.
Set up the API test the agent will run
Install the CLI and the recorder in your app’s project, then write the instructions for your coding agent:
npm install -D stresseur stresseur-recorder
npx stresseur install-skill
install-skill writes .claude/skills/stresseur/SKILL.md, a section in AGENTS.md, and .cursor/rules/stresseur.mdc. Then record a session while you use your app, and generate flows from it:
npx stresseur record
npx stresseur generate
The flows are files under api-tests/, named *.yamlflow.yaml. The agent can read each step and edit it like any other file, and you can review the change in a diff. They are generated from recorded, real usage, so they describe behavior your app already has. The page for coding agents shows the same setup. If you would rather start with one command, npx stresseur init has a --json option for tools and coding agents.
Point the flows at the app the agent just changed. They read the app’s URL from APP_URL, locally and as the CI repository variable, so set it to the instance the agent just changed.
Red: make the API test fail first
Stresseur flows come from recorded usage, and writing missing flows is not something its AI test engineer does yet. So the failing test comes from you or from the agent, as an edit to a flow file.
Take a shop where products are created through the API, and a new requirement that every product carries a SKU. Before touching the handler, edit the create-product step so it sends a SKU and expects it back, then run the flow:
npx stresseur flow run api-tests/checkout.yamlflow.yaml checkout
Use your own file and flow name. The run should fail, and it should fail for the right reason. A useful red names the step and the server’s answer. In our test of a change like this, the flow’s failure named the step and the server’s answer, while the UI test’s failure said element(s) not found.
If the flow passes, it does not check the new behavior yet, so fix the test before you ask the agent for anything. If the failure does not name a step, fix that too. A red you cannot read gives the agent nothing to act on.
Green: let the agent make it pass
Give the agent the failing test and one rule: fix the code, not the assertion, unless the requirement itself changed, and say so when it did. A prompt that works:
Make the create-product flow pass. Read the failing step and the server’s answer before editing anything. Do not edit files under
api-tests/. Run the flow again when you are done.
We measured one version of this. We made the API require a SKU on new products, which broke both the flow and the UI test. The same coding agent, with the same model and prompt, fixed each test 3 times from a fresh copy. The median time to green was 21 s for the flow and 61 s for the UI test. That is one app, not a general benchmark.
The agent also gets exit codes it can branch on. flow run exits 0 when done, 99 when a threshold failed, 108 when aborted and 1 when it could not run. If a variable the flow uses is not set, it stops before the first step and names it.
Refactor, and which tests run after each change
Refactoring is where a fixed test earns its keep, because behavior must not change. After each edit, the agent runs the flows that touch the code it changed with npx stresseur flow run. Before you push, run npx stresseur ci, and run the same flows on every pull request as in API smoke tests on every pull request. It runs each flow in api-tests/ 13 times (1 warm-up, 12 measured), prints per-step timings and exits 1 if any step failed.
Use flow run for the quick loop after an edit and ci before you push. Unit tests still belong in the loop, and the unit test vs integration test comparison covers what each layer catches. The API flow is the check that the pieces work together.
Keep the suite strict while the agent edits, since tests that nobody maintains stop being trusted, as the guide to keeping API tests current explains. Generated flows check more than the status code: after a create, a later read of the list or page must hold the new id, or a value the user typed, made unique per run. Read any diff under api-tests/ the way you read a change to a production file, because a loosened check changes what you test.
Claude Code, Cursor and Codex: the same loop
In Claude Code, the skills documentation says project skills load from .claude/skills/ in the directory where you start it and in every parent directory up to the repository root. In Cursor, the rules documentation says project rules live in .cursor/rules as .mdc files and are version-controlled. The --agent flag of install-skill takes claude, codex, cursor or all.
Codex is not a listed Stresseur integration. The listed coding-agent integrations are Claude Code and Cursor. The install command also writes a section in AGENTS.md, which describes itself as a simple, open format for guiding coding agents. Whether a given agent reads that file is a question for that agent’s own documentation. The loop itself is ordinary commands, so you can paste them into a Codex prompt.
What to do next
Pick the one journey that matters most, such as checkout or login, and write its next change test first. Watch it fail, let the agent make it pass, and run the flows after every edit. Move to the next journey once the first one runs on every change.
Frequently asked questions
Does TDD work with AI coding agents?
Yes, as a way of working: write the test, watch it fail, ask the agent to make it pass, then refactor with the test still running. We have not measured whether TDD improves agent output in general, and the one measurement in this post comes from a single app.
Can Cursor follow the same loop?
Yes. `npx stresseur install-skill` writes `.cursor/rules/stresseur.mdc`, and the flows are plain files in `api-tests/` run with plain `npx stresseur` commands, so nothing in the loop depends on the editor.
Does Stresseur write the failing test for me?
No. Writing missing flows from the AI test engineer is not available yet. Flows are generated from recorded usage, and you or the agent edit a flow file to describe new behavior.
How do I stop the agent from weakening the test?
Tell it to fix the code, not the assertion, unless the requirement itself changed, and to say so when it did. Review any change under `api-tests/` the way you review production code.
How do I run a flow from the command line?
Run `npx stresseur flow run` with the path to the flow file and the flow name. It exits `0` when done, `99` when a threshold failed, `108` when aborted and `1` when it could not run.