Test-driven development loop

Write one failing test, make it pass with the least code, clean up while the tests stay green, repeat. The loop is useful for agents for a specific reason: a test that has never failed proves nothing. If you only ever see tests pass, you cannot tell a test that checks the behavior from one that checks nothing. Watching the failure is what makes the later pass meaningful.

Each step produces evidence: command output you can quote. Without it the loop has not been run, only described.

This playbook covers the procedure, not test strategy or test-double theory.

Core principles

Step 0: Prepare

1. Find the project's test command and how to run a single test (check AGENTS.md, CLAUDE.md, the Makefile, package.json, composer.json, CI config). Do not guess.
2. Run the existing suite once. Record the result. A suite that is already red must be understood before you add to it.
3. Pick the smallest behavior to start with. If a spec exists with requirement IDs and WHEN/THEN criteria (see spec-driven-development), each criterion is one or more tests.
4. Find the right seam (see below) and an existing test file in the same area to copy conventions from.

The loop

1. Red: write one failing test

Write a single test for one behavior. Name it after the behavior (rejects_expired_token), not the method. Use arrange, act, assert, with one reason to fail.

Run only that test. Show the output. Check two things:

• It fails. If it passes, the behavior already exists or the test checks nothing; stop and find out which.
• It fails for the right reason: an assertion about the missing behavior, not a syntax error, missing import, wrong fixture, or setup crash. Fix the test until the failure message describes the missing behavior.

State in one line what the failure shows, for example "Expected 401, got 200: expired tokens are accepted."

2. Green: write the minimum code

Write the simplest code that makes this test pass, even if it looks naive. Returning a constant is allowed if only one test exists; the next test will force the general form. Do not add parameters, branches, or abstractions no test demands.

Run the single test. Show the output. Then run the surrounding suite and show that too. A passing test next to a newly broken one is not green.

3. Refactor: clean up on green

With all tests passing, remove duplication, improve names, simplify structure, in code and in tests. Run the tests after each small change and show the result. Never skip this step: green code written to pass one test usually needs shaping. Do not change behavior here; behavior changes start a new red.

4. Repeat

Pick the next behavior: another criterion, an edge case, an error path. Common ones: empty input, boundary values, invalid input, permission denied, upstream failure, duplicate request. When the list from the spec is done, commit (one logical change per commit, using the project's convention).

Excuses to skip red

These are the reasons agents give for skipping the first step. Each has a response.

If you notice yourself writing production code before a red test, delete it and start from the test. The deleted code will be rewritten faster and tighter.

Test at the right seam

A seam is a place where you can observe behavior or substitute a dependency without editing the code under test. Pick the lowest seam that still exercises the behavior from the outside.

Rules of thumb:

• Assert on outputs and observable state, not on which private methods ran.
• Inject the clock, randomness, and I/O so tests control them.
• If a test needs more than a few lines of setup, the code under test has too many dependencies. Treat that as a design signal.
• A test that breaks when you rename a private method but behavior is unchanged is coupled to implementation. Move it up a seam.

Never edit a test just to make it pass

When a test fails after your change, decide which of these is true before touching anything:

1. The code is wrong. Fix the code. This is the usual case.
2. The test encodes behavior that has intentionally changed (by the spec, ticket, or user). Update the test, and say in your message which requirement changed and why.
3. The test is wrong or flaky (bad fixture, hidden order dependence, time dependence). Fix it, and say what was wrong and how you know.

Never loosen an assertion, delete a test, skip a test, or widen an expected value without writing one of those explanations. If you cannot say which case applies, stop and ask. A silently edited test is the most common way an agent turns a red suite green without fixing anything.

Bug fixes

1. Reproduce the bug with a test that fails for the reported reason. Show the red. If you cannot reproduce it in a test, you do not yet understand the bug (see debugging).
2. Fix the cause, not the symptom. Show the green.
3. Keep the test as a regression test. Name it after the behavior, and reference the ticket or issue if the project does that.

Legacy code with no tests

Do not refactor or change untested code blind. First pin what it does now:

1. Choose the seam closest to the change (see references/legacy-and-characterization.md).
2. Write a characterization test: call the code with a realistic input, assert whatever it returns today, run it, and keep that assertion even if the behavior looks wrong. The test records current behavior; it is not a judgment of it.
3. Cover the paths your change will touch: normal case, edge cases, error cases.
4. Now make your change in the normal loop: new failing test for the new behavior, minimum code, refactor.
5. Mark behavior that looks like a bug in a note or ticket. Do not fix it in the same change unless asked.

When the loop gets stuck

Quick checklist

• Test command found, baseline suite run and recorded
• Each behavior: one test, red output shown, failure reason matches
• Minimum code written; single test and surrounding suite green, output shown
• Refactor done on green, tests re-run
• No test edited without a stated reason
• Bug fixes keep a regression test
• Legacy changes started with characterization tests
• Final full suite, lint, and static analysis output captured (verification-before-completion)

Reference files

Integration with other skills