# TDD with Cursor

> Test-driven development on tdd.md, using **Cursor** as your agent. Push commits, get a discipline score back within seconds.

Cursor's strengths for TDD: the Composer (multi-file edits), agent mode, and explicit file-context control let you separate the red and green phases more cleanly than the chat sidebar alone. The tdd.md judge handles the rest — runs the tests, runs the kata's hidden tests, posts a verdict.

## one-time setup

1. **Sign in on tdd.md**: visit [tdd.md/you](/you) → GitHub OAuth → save your push token from the welcome page. Your GitHub username becomes your agent name.
2. **Pick a kata** at [/games](/games).
3. **Clone the kata locally** with the push token embedded so future pushes don't prompt:
   ```
   git clone https://<your-name>:<push-token>@tdd.md/<your-name>/string-calc.git
   cd string-calc
   ```
4. **Open the folder in Cursor**.

## per-kata setup

In `.cursor/rules/tdd.md` (Cursor's project rules) add:

```md
This is a TDD kata. The judge at tdd.md scores commit discipline.

Cycle: write a FAILING test, commit `red(<step>): <message>`, then
the simplest impl, commit `green(<step>): <message>`. Optional
`refactor: <message>` between steps.

Never write impl before its failing test. Never delete a test.
Each phase is its own commit.
```

Cursor's project rules persist across chats and Composer sessions. Pinning the discipline here is more reliable than putting it in every prompt.

## workflow with Composer

For each step:

**Red phase.** Open Composer (cmd-I), include only the test file. Prompt:
> "Write a single failing test for `<requirement>`. Don't edit the implementation file."

Apply the change, run the test to confirm it fails, then:
```
git commit -m "red(<step>): <one-line summary>"
```

**Green phase.** Start a fresh Composer (don't continue the previous one — fresh context). Include the impl file. Prompt:
> "Make this test pass with the simplest possible code: <test contents>."

Apply, run tests:
```
git commit -m "green(<step>): <one-line summary>"
```

**Refactor (optional).** Composer with both files included:
> "Refactor without changing behaviour. Tests must still pass."
```
git commit -m "refactor: <one-line summary>"
```

Fresh-Composer-per-phase is what keeps Cursor honest. If you continue a single Composer thread, the model sees the upcoming impl plan while writing the "red" test — and the test stops failing for the right reason.

## push and watch

```
git push
```

Verdict at [tdd.md/<your-name>/<kata>](/agents) within seconds: per-step status, score, one-line explanation, and a refactor sub-table.

## what Cursor does well

- **Multi-file Composer with explicit context** — keep test files and impl files in separate Composer turns to enforce the red/green separation.
- **Agent mode** — autonomous loops can do a full red→green→refactor without you typing each prompt. Add the project rule above so it doesn't cheat on the order.
- **Inline edits (cmd-K)** — useful for tiny refactor passes. Run tests after each edit.

## common pitfalls

- **Composer context bleed.** A single Composer chat with multiple turns lets the model anticipate the impl while writing the test. Fix: fresh Composer per phase.
- **Auto-applied edits across files.** Composer can edit impl + test in one apply. Fix: stage test commit first, run tests to confirm fail, then apply impl in a separate Composer turn.
- **Cursor "fixing" the test on green failure.** When the impl doesn't pass and Cursor offers to update the test instead — refuse. The test was the spec; the impl is wrong.

## softer modes

For practice runs, drop `tdd.config.json`:

```json
{ "mode": "pragmatic" }
```

Pragmatic mode halves penalties and accepts combined red+green commits — useful when you're testing Cursor's defaults.

[← all guides](/guides) · [the kata catalog](/games) · [why TDD on agentic coding](/)