Agent chat workflows in Cursor

An agent chat in Cursor produces trustworthy multi-file changes when the prompt carries a definition of done the agent can check itself: approved failing tests, the commands that gate the result, and the evidence to report. With those three in place, test and type output judges the change, and a stalled chat is restarted rather than argued with.

You type “add organisation invites” into Cursor’s agent. Twenty minutes later it has created an invites module with its own error format, skipped the permission middleware your other routes use, and “fixed” a failing test by changing its assertion. The chat is now 30 messages long, every correction makes it worse, and you still cannot say whether the feature works without reading 600 lines.

This page is for developers who hand feature-sized work to Cursor’s agent every day. It covers the chat itself: how to open it, what to put in the prompt, how to check the result, and when to throw the chat away. This page covers the Cursor 3.x line; the current release on 2026-10-12 is Cursor 3.24 (2026-10-09, Cursor’s release notes). Plan Mode, Rules, Hooks, Worktrees, Subagents, Cloud Agents, and /goal were first checked against Cursor’s docs on 28 August 2026. Cursor’s help and docs, checked 2026-10-12, say that Cmd+I (Ctrl+I on Windows and Linux) opens the Agent panel and Shift+Tab cycles through the modes, that the run modes are Auto-review, Allowlist and Run Everything (Settings > Agents > Approvals & Execution), and that Cursor names no single default model. Shortcuts and run modes change between releases, so confirm them in your build.

What a well-run Cursor agent chat gives you

• A seven-step loop that takes one task from request to a pull request carrying its own evidence.
• Five copy-paste prompts: test-first feature, Plan Mode research, debugging from a stack trace, one-file-at-a-time migration, and the pre-PR gate.
• A git check that proves the agent did not weaken the tests you approved.
• Clear signals for when to supervise a chat, when to let it run, and when to stop and start over.

How does one agent chat go from request to verified change?

Every task on this page follows the same loop. The steps that people skip are 3 and 6, and they are the two that make the result provable.

1. Scope the task to one outcome. One feature, one bug, or one migration step per chat. If you cannot say what “done” looks like in one sentence, the task is too big or not yet understood.
2. Anchor it in your code. Attach the file that already does the same thing correctly with an @ reference, plus the files the change must touch. Context management in Cursor covers what to attach and what to leave to the agent’s own search.
3. Fix the definition of done. Ask for failing tests first, read them, and commit them. They are the specification; the implementation is whatever makes them pass.
4. Put the gates in the prompt. Name the exact commands the agent runs after each change: tests, type check, lint.
5. Ask for an evidence report. Files changed, command output, assumptions. “Done” without output is not done.
6. Check the evidence, not the diff. Confirm the approved tests are unchanged, the gates are green, and the report matches the task.
7. Close the chat. Commit, write a handoff note if the work continues, and start the next task in a new chat.

Write the definition of done before the agent writes code

The most effective change to an agent chat is ordering: tests first, implementation second. Tests written before the code describe the behaviour you asked for. Tests written after the code describe whatever the agent happened to build, so they pass by construction and prove nothing.

Send the prompt in two turns. The first turn stops after the tests, so you can read them before any implementation exists.

Copy-paste prompt: test-first feature, turn one

Feature: organisation invites.

Acceptance criteria:
- POST /api/orgs/:orgId/invites with a valid email returns 201 and stores a
  pending invite that expires in 7 days.
- An email that is already a member returns 409 in the error format from
  @src/lib/errors.ts.
- A caller who is not an org admin returns 403 (use requireOrgRole from
  @src/middleware/auth.ts).
- POST /api/invites/:token/accept adds the user to the org and marks the
  invite accepted; an expired token returns 410.

Write ONLY the tests now, in src/routes/__tests__/invites.test.ts, following
the structure of @src/routes/__tests__/members.test.ts. One test per criterion,
plus one for the expired token. Run `npx vitest run src/routes/__tests__/invites.test.ts`
and confirm every test fails for the right reason (missing route or handler,
not a syntax or import error). Do not create any implementation file.
Report: the test names and the failure message for each.

Read the test names and assertions, not the setup code. Each assertion should match one criterion. If one is missing or too weak (for example, it checks the status code but not that the invite is stored), say so now. Then commit the tests on their own:

git add src/routes/__tests__/invites.test.ts
git commit -m "test: spec for organisation invites"
git tag spec-invites

That commit is the contract, and the local tag spec-invites marks it so you can compare against it later. The second turn implements against it.

Copy-paste prompt: test-first feature, turn two

The tests in src/routes/__tests__/invites.test.ts are committed and approved.
Implement the feature until they pass.

Anchor: follow @src/routes/members.ts for route structure, validation and
error handling. Store invites through a new table defined next to the members
table in @src/db/schema.ts.

Rules:
- Do NOT edit, skip or delete any test. If you believe a test is wrong,
  stop and explain why instead of changing it.
- Do NOT touch files outside src/routes/, src/db/ and src/services/.

After each change run:
1. npx vitest run src/routes
2. npx tsc --noEmit
3. npm run lint
Iterate until all three pass.

Report: files changed, the last 15 lines of each command's final output,
and every assumption you made.

The full test-first discipline, including mutation testing to prove the tests can catch a bug, is on test-driven development in Cursor. The acceptance-criteria format comes from executable acceptance criteria.

Use Plan Mode when you cannot yet write the acceptance test

Some tasks start with a question, not a specification: “how do we add usage-based billing?” If you cannot write the acceptance criteria, you are not ready for tests, and the agent is not ready to edit code. Cursor’s Plan Mode “creates detailed implementation plans before writing any code”, and the plan it produces is a document you can edit before anything is built. Switch the chat to Plan Mode before sending; Cursor’s agent modes shows how.

Copy-paste prompt: Plan Mode research

Plan, do not implement: we need usage-based billing for API calls.

Research @src/api/ and @src/services/billing/ first. Then produce a plan with:
1. The files that change and the files that are new, with one line each on why.
2. The order of work, as steps small enough that each ends with a passing
   test run.
3. The acceptance criteria for each step, written so each one becomes a test.
4. Every open question you cannot answer from the code (pricing rules,
   rounding, what happens when metering is late). Ask them; do not guess.
5. What you will NOT change.

Edit the plan until the criteria are ones you would sign. Then build one step per chat, using the test-first prompts above with that step’s criteria. A plan that is too large to review in five minutes is too large to build in one chat. Cursor’s agent modes compares Plan Mode with the other ways to start a chat.

Put the gates in the prompt and ask for evidence

A prompt that ends with the feature description leaves verification to you. A prompt that ends with the commands to run and the evidence to report makes the agent verify, and turns your review into reading its output. Match the gate to the task:

Task	Gate the agent runs	Evidence you check
New feature	Approved tests, full suite, type check, lint	Approved test file unchanged; all green
Bug fix	A new failing test that reproduces the bug, then the suite	The test failed before the fix and passes after
Refactor	The existing suite, unchanged; type check	No test file in the diff; public exports unchanged
Migration step	The tests for the one migrated file; the suite	Only the named file and its imports changed
Dependency upgrade	Full suite, type check, build	Build output and the changelog items the agent checked

Whether the agent runs these commands without asking you depends on your run mode. Cursor documents terminal control on its Run modes page (under Agent security); keep test, type-check, and lint commands allowed, and keep anything that pushes, deletes, or reaches the network behind approval. Privacy and security for Cursor teams walks through that setting.

Debug from runtime evidence, not from a description

“The webhook sometimes fails” gives the agent nothing to test. A stack trace and a reproduction give it file paths, line numbers, and a failure it can make disappear. Forbid source edits until a failing test reproduces the bug; a plausible explanation of the wrong cause reads exactly like a correct one.

Copy-paste prompt: debug from a stack trace

Production error from our logs:

TypeError: Cannot read properties of undefined (reading 'email')
    at processWebhook (src/api/webhooks/stripe.ts:47:28)
    at handleRequest (src/middleware/router.ts:112:5)

It happens on customer.subscription.updated events.

Phase 1, no source edits:
- Read @src/api/webhooks/stripe.ts and the event types it handles.
- List up to three candidate causes with the evidence for and against each.
- Write one failing test in src/api/webhooks/__tests__/stripe.test.ts that
  reproduces the error with a realistic event payload. Run it and show it fails
  with this TypeError.

Stop and wait for my go-ahead.

Phase 2, after I approve the test: fix the handler so the test passes, run
`npx vitest run src/api/webhooks` and `npx tsc --noEmit`, and report the
root cause in two sentences.

When the bug only appears under load or in timing, add temporary logging, reproduce it yourself, and paste the logs back; then have the agent remove the logging in the same chat. Bug hunting with Cursor covers the intermittent cases.

Migrate one file at a time

“Migrate the API from Express to Hono” in one prompt produces a diff nobody can check. One file per step, each gated by its own tests, produces a sequence of small diffs where the first one sets the pattern for the rest.

Copy-paste prompt: incremental migration step

We are migrating our HTTP layer from Express to Hono, one route file at a time.

This step: @src/api/health.ts only. Convert it to Hono, register it in
@src/server.ts next to the remaining Express routes, and keep the URL and the
response body identical.

Do NOT change any other route file.
Run `npx vitest run src/api` and `npx tsc --noEmit`.
Report: the diff summary (`git diff --stat`) and the test output.
Then write the conversion pattern you used as five bullet points, so the next
chat can apply it to the next file.

Commit after each step. Start the next file in a new chat with the five-bullet pattern and the migrated file attached as the anchor: Convert @src/api/users.ts following the pattern in @src/api/health.ts. Large migrations as a programme are covered in migration with Cursor.

Run the pre-PR gate without letting the agent edit tests

End the task with one pass that makes the branch ready for review. The rule that matters is the one about test files: an agent told to “make the tests pass” will change assertions if nothing stops it.

Copy-paste prompt: pre-PR gate

Prepare this branch for review against main.

1. Run `npx tsc --noEmit` and fix every type error.
2. Run `npm run lint` and fix every issue.
3. Run `npx vitest run` and fix failures in the SOURCE code only. Do not modify
   any test assertion, skip a test, or delete a test. If a test looks wrong,
   list it with your reasoning and leave it failing.
4. Remove debug logging added on this branch.
5. Run all three commands again.

Report as a table: check, final status, what you changed to get there.
Then list anything a reviewer should look at first, with file and line.

How do you verify the chat’s output without reading every line?

You check four pieces of evidence, in this order, and read code only where one of them points you.

1. The approved tests did not change. This command prints nothing when the test files and the test-runner configuration are the same as in the commit you approved:

   git diff --stat spec-invites -- '*.test.ts' '*.spec.ts' 'vitest.config.*' package.json

   spec-invites is the tag you set on the spec commit; the comparison includes uncommitted changes. Any output means the agent touched the specification or how it runs: read that hunk first. The command does not list new files, so also run git status --short to see new, untracked files.

2. The gates are green on your machine. Re-run the test, type-check, and lint commands yourself rather than trusting the quoted output. It takes seconds and catches a report that was copied from an earlier run.

3. The diff stays inside the fence. git diff --stat main should list only the directories you allowed. A file outside them is either a missed dependency (fine, if the report explains it) or scope creep (revert it).

4. The report’s assumptions are ones you accept. Each listed assumption is a decision the agent made for you. Reject any you would not have made.

Who signs off: you approve the tests before implementation, because they are the specification. The pull request then carries the evidence, and your reviewer and any automated reviewer such as Bugbot check that it matches the task. The format for that evidence is the evidence bundle.

When should you supervise the chat and when can it run?

Supervision is a function of how well the task is specified, not of how much you trust the model.

Situation	How to run it
Approved tests exist, gates are in the prompt, scope is fenced	Let it run; check the evidence when it reports
Acceptance criteria unclear	Plan Mode first, then build step by step
Touches auth, payments, data deletion, or migrations on shared data	Supervise each step; approve every command that is not a test or check
Long, well-specified work you do not need to watch	A Cloud Agent, which runs in an isolated VM in the cloud with a full development environment
Two or more tasks at once	One Worktree per task, so the agents never share a checkout
A goal with a checkable end condition, such as “all tests in src/api pass”	/goal, still rolling out (Cursor docs, checked 2026-10-12); see the /goal command

Cursor 3.24 (2026-10-09) added a Goal pill above the prompt. Since 2026-08-19, follow-ups steer the agent: Cursor’s changelog says “Follow-ups wait for the next tool call instead of cutting the agent off mid-action”.

Three more chat controls from Cursor’s help and docs (checked 2026-10-12):

• Enter queues a message; Send a follow-up now steers the active turn at the agent’s next tool call.
• /side or /btw starts a side chat.
• Any skill with a valid frontmatter block can back a Custom Mode, which “keeps the skill in context for the whole session”.

Cursor’s agent can also delegate to subagents, “specialized AI assistants that Cursor’s agent can delegate tasks to”. Delegation helps when a subtask, such as searching a large codebase, would fill the main chat with material the rest of the task does not need.

When should you stop a chat and start over?

A chat is a context window. Every failed attempt, dead end, and superseded plan stays in it, and the agent keeps reasoning over them. Stop and restart when you see any of these:

• The agent makes the same mistake after you corrected it twice.
• It edits files you told it not to touch.
• It changes a test to make it pass.
• Its answers stop referring to your code and become generic.
• You no longer remember which of its changes you have accepted.

Restore the last good state first. Revert to your last commit with git restore or git reset, or, if your Cursor version offers checkpoints, restore one (see checkpoints and branching). Then open a new chat and put the failure into the prompt, so the new chat does not repeat it.

Copy-paste prompt: restart after a failed chat

Previous attempt failed: the agent wrote raw SQL instead of using the Drizzle
query builder, and changed the assertion in invites.test.ts line 42.
All database access goes through @src/db/queries.ts. The tests in
src/routes/__tests__/invites.test.ts are approved and must not change.
Continue from: FAILED_STEP

FAILED_STEP is one sentence from your plan. When the work continues across chats on purpose, close the old chat with a handoff note instead; the prompt for it is on context management in Cursor.

What breaks in Cursor agent chats, and how to recover

The agent edited a test to make it pass

Symptom: the suite is green, and the git diff check above prints a test file. Recovery: git checkout spec-invites -- src/routes/__tests__/invites.test.ts, then tell the agent the test is restored and approved and that it must change the source instead. If it happens twice, write the rule into a project rule so every chat starts with it (project rules in Cursor).

The agent loops between two failures. It fixes test A, breaks test B, fixes B, breaks A. Stop it. The loop usually means the two tests encode conflicting requirements, or the agent is fighting its own earlier change. Revert to the last green commit, decide which requirement wins, and restart with that decision in the prompt.

The code works but ignores your conventions. The anchor is missing or the convention is not visible in code. Add the anchor file with @. If the convention is something code cannot show (for example, “never call the payments service from a route handler”), put it in a project rule.

The agent uses an outdated library API. The model’s training data is older than your dependency. Tell it the installed version (from package.json) and ask it to check current documentation before writing code, or add a documentation MCP server such as Context7 (npm package @upstash/context7-mcp, version 4.1.1 on 26 September 2026). The Context7 page gives this remote-server entry for ~/.cursor/mcp.json; add an Authorization header with your Context7 key for higher rate limits:

{
  "mcpServers": {
    "context7": { "url": "https://mcp.context7.com/mcp" }
  }
}

General setup is on MCP setup for Cursor.

The change spread across the codebase. The prompt did not fence scope. Revert the files outside the fence with git restore <path>, and add an explicit “Do NOT touch files outside …” line to the next prompt.

The agent ran a command you did not want. Your run mode allowed it. Undo the effect first (revert files, restore the local database from its migration), then tighten the setting so that command needs approval next time.

Where to go next with Cursor agent chats

• Build your first AI-assisted feature, if you have not yet taken one feature through Plan Mode and tests end to end.
• Prompt templates for Cursor’s agent, to save the prompts on this page as commands or skills the whole team shares.
• Large codebase strategies, for when the agent cannot hold enough of the project to follow these prompts.
• The Agents Window and Projects in Cursor, to run several of these chats in parallel.
• The same loop in the terminal: multi-file workflows in Claude Code and prompt engineering for Codex.