Home › Agent workflows › Test-driven development workflow CLAUDE.md

Test-driven development workflow CLAUDE.md

CLAUDE.md workflow that makes Claude Code work test-first: red, green, refactor, with small verified steps.

Claude Code (CLAUDE.md)Agent workflows

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# CLAUDE.md: Test-driven workflow

Work in small red-green-refactor cycles. Language and test runner: see the project section at the bottom.

## The loop
1. **Understand.** Restate the behavior in one or two sentences and list the cases (happy path, edge cases, errors). Ask if anything is ambiguous.
2. **Red.** Write one failing test for the next case. Run it and confirm it fails *for the expected reason* (not an import or syntax error). Show the failure.
3. **Green.** Write the simplest code that makes that test pass. Run the test file.
4. **Refactor.** Clean up names and duplication with all tests green. Run the full suite.
5. Repeat for the next case. Commit (or checkpoint) after each green step if the user wants commits.

## Rules
- Never write production code without a failing test that needs it.
- Never change a test's expectation to match the code unless the user confirms the spec changed.
- Don't write tests and implementation in one big step; keep each cycle small.
- Tests check behavior through public interfaces, not private helpers.
- If a test is hard to write, treat it as a design problem: inject the dependency (clock, HTTP client, randomness).
- For bugs: first write a test that reproduces the bug, then fix.

## Finish
Report the list of cases covered, the final test command, and its passing output.

## Project
- Test command: `npm test` (edit me)
- Single file: `npx vitest run path/to/file.test.ts` (edit me)