How to Use a Failing Test as an AI Coding Spec

Give the agent one named task, only the context it needs and a check you can rerun. A task shaped this way produces a diff small enough to review and a result you can repeat.

Each move fails in its own way. Without a boundary, the agent edits files you never meant to open, and the diff becomes hard to read. Thin context fails more quietly: the code compiles and the tests pass, but the change ignores patterns the rest of the repo follows. Without a check you can rerun, you are taking the agent's word that the work is done.

Asking for a plan before the agent writes code is the easiest step to skip. It means a short wait while nothing visible happens, and the price of skipping it shows up later, in review.

If the plan names files you didn't expect, you learn that before any code exists. If it names the right files, you have a list to check the diff against. Once four hundred lines of diff are on screen, changing the approach means throwing that work away.

Yes. Treat the frame below as a starting point. Fill in your own files, constraints and done state, and keep the plan step, so the agent commits to an approach before it writes code.

Task: [one outcome]
Context: [files, errors, docs and examples]
Boundary: [what not to touch]
Done when: [test, typecheck, screenshot or review proof]

Before editing, write a short plan with files, risk and checks.

Fill the Context line with things the agent can open: file paths, the exact error text and the doc or example to follow. Paste errors instead of paraphrasing them, because a paraphrase drops the detail the agent needs to trace the cause.

The Boundary line is easy to leave out, and in our view it does the most work. Without it, every file the agent can reach is fair game. You end up reviewing incidental edits to config, imports and helpers you had forgotten about, mixed in with the change you wanted. Naming what not to touch takes a few seconds, and reverting stray edits afterwards takes far longer.

"Done when" has to name something you can run or look at: a test name, a typecheck, a command whose output you can read, or a screenshot of one specific state. "Done when the bug is fixed" doesn't count. It hands the judgment back to the agent, and the agent will report that the work is finished either way.

The habit that matters most for a team is leaving a trail the next reviewer can follow. The steps below keep the prompt and its proof attached to the change.

1. 1Pick one real backlog item with a clear owner and expected result.
2. 2Add only the context the agent needs: files, failing output, constraints and done state.
3. 3Ask for a plan before code when the task touches more than one file.
4. 4Run checks that match the risk: unit test, typecheck, visual pass or review checklist.
5. 5Capture the prompt, diff, result and reviewer note so the workflow can be repeated.

Match the effort to the change. A one-file fix needs a clear done state and a typecheck, and a plan adds little. A change across several files is where a plan pays for itself, and where the check should include tests and a reviewer who knows that code.

Keep whatever lets someone rerun the work or pick it up later. A finished task is the merged code plus a short trail that shows how it got there.

• The prompt or plan that shaped the work.
• The files changed and the reason each file changed.
• The command, screenshot or review note that proved the result.
• The rule, checklist or template you would reuse next time.

The last item pays off over time. A rule or template saved from one good run means the next run starts from what already worked, not from a blank prompt.

Plan modeA mode that makes no edits: it researches the codebase and produces an editable plan you review before any code changes. Press Enter for the full definition. researches the repo, asks clarifying questions and writes a Markdown plan that you and the agent refine before any code exists. The presenter of Cursor's QA workshop found that it copes with a vague, ill-formed prompt and uses the agent to check your assumptions. Treat the plan as a rough draft: a spec that sits between your intent and the implementation.

For test-driven work with agents, run two plans. The first plans and writes a skeleton of tests that pins the functional requirements. The second plans the logic that turns those tests green. Cursor's best-practices guide for agents makes the same point: agents perform best when they have a clear target to iterate against, and a test skeleton gives them one.

Because it has already shown that it can fail. The old testing discipline is never to trust an automated test you did not see fail, and a red test clears that bar before you write a line of the fix. A written spec cannot clear it at all. A green test that nobody has seen go red might assert nothing, and you would have no way to tell.

A failing test is still incomplete. It is a spec with exactly one example in it, and a patch that satisfies one example is not necessarily the behavior you wanted. That is fine when you know the assertion is representative. It stops being fine when the test covers the happy path and the bug lives two branches over.

Put the test file in the boundary, not in the scope. If the check and the code being changed are the same file, "done when the test is green" carries no information. Say which file the fix belongs in, and say that the test must not be touched.

Sometimes the test itself is wrong. That is a real task but a separate one. On a suite that has drifted from the code, it may even be the more common job. Decide which job you are doing before you prompt, because a run that changed both the assertion and the implementation tells you nothing.

Read the changed-files list before you read the result. If the test file changed, a green run proves nothing.

One. With two failures in play, you cannot tell which one the patch fixed. The agent also chases both at once, which is how a small fix ends up spread across several files.

Give the loop its own session, too. Guidance from Cursor's QA workshop is to keep the context window as empty as you can for test work, with a fresh agent that only runs and writes tests. In a long conversation, the presenter warned, rule context can get overwritten as the window fills, and the agent stops following your rules without saying so.

A Cursor field engineer's rule of thumb is to run /summarize at roughly 50 to 60 percent full. Check the context ring between runs, because a rerun loop fills the window without ever feeling long.