Skip to content

Guide

How to Use a Failing Test as an AI Coding Spec

By The Learn Cursor Editorial TeamUpdated

A failing test is one of the best specs for an AI coding agent because it defines the target behavior and the check. Give the agent the failing output, relevant file, expected behavior and one repair boundary. Ask it to make the smallest patch that turns the test green.

Cover image for How to Use a Failing Test as an AI Coding Spec

What is the working pattern for failing test as an AI coding spec?

Move
Start with a bounded task
Use this when
Developers using test-first or bug-fix loops with AI coding agents.
Proof to save
Issue, files, checks and owner are named
Move
Give the agent context
Use this when
The repo has patterns the agent must follow
Proof to save
Prompt cites files, errors and constraints
Move
Review the diff
Use this when
The task changes production code
Proof to save
Changed files, test output and risks are visible

A good AI coding workflow is specific enough to review and small enough to recover.

Inspectable agent workflow

Interactive diagram. Use Tab to move through hotspots or use the step controls when shown.

ContextFiles and taskPlanBefore editsChangeSmall patchTestEvidence▲ GATEReviewHuman handoff
1/5
Context: Name the issue, repo area, source files and constraints.

Use this loop when the change is larger than autocomplete and smaller than a full project rewrite.

Practice view
Learn Cursor module with a learning section, diagram and checks

The public guide connects to lessons, recall and readiness checks inside Learn Cursor.

Can I adapt the prompt to my repo?

Prompt composer

Interactive diagram. Use Tab to move through hotspots or use the step controls when shown.

Prompt output
Task: Add keyboard support to the command menu

Context:
- Use src/components/command-palette.tsx and current button patterns

Boundary:
- Do not change routing or auth code

Done when:
- Run npm run lint and test keyboard focus in browser

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

Keep the static prompt frame on the page. The builder only helps readers adapt it to their repo.

Change the fields, then copy the prompt into your AI coding tool.

Reusable prompt frame
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.

How should a team run failing test as an AI coding spec?

  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.
Prompt frame

Task, context, constraints, done state and checks.

Review habit

Open the diff, read changed files and rerun the check yourself.

Team artifact

The guide uses one failing assertion as context, boundary, patch and rerun steps.

What should you keep after the run?

  • 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.

Frequently asked questions

Who is How to Use a Failing Test as an AI Coding Spec for?

Developers using test-first or bug-fix loops with AI coding agents.

What makes this page credible?

The guide uses one failing assertion as context, boundary, patch and rerun steps.

What should I do next?

Start with one real repo task, capture the prompt and review the result before scaling the workflow.

Sources & last verified

Cursor ships frequently. Facts verified against primary sources on June 23, 2026.

Keep reading