Cursor agent modes: when to plan, ask, build and debug

Cursor’s agent modes set what the agent may change in a conversation. Plan Mode researches the codebase and produces a reviewable plan before any file changes; Agent mode edits files and runs commands. Some builds also offer a read-only Ask mode and an evidence-gathering Debug Mode. The right mode depends on how well the task is already specified.

Documentation freshness

Covers: the Cursor 3.x line, checked on 26 September 2026. Plan Mode and Agent mode were verified against Cursor’s docs on 28 August 2026, and Cursor’s own @cursor/sdk 1.0.x package (checked on npm on 26 September 2026) exposes exactly two conversation modes, agent and plan. Cursor’s pages on Ask mode, Debug Mode and keyboard shortcuts could not be re-checked on 26 September 2026, so this page treats Ask and Debug as optional and names no shortcut. Every workflow below works with Plan Mode and Agent mode alone.

This page is for developers who drive Cursor’s agent every day and for tech leads who want the team to use modes the same way. The situation it solves: a ticket needs changes to an API route, three React components, a migration, and the tests. You type it into Agent mode, and 90 seconds later a diff touches 14 files, several of them in the wrong direction. The model did not fail. It was asked to build before anyone, you included, knew the shape of the change.

What you’ll walk away with from Cursor’s modes

• A decision table that maps the task in front of you to a mode, what that mode may change, and the evidence that ends it
• Four copy-paste prompts: a plan with acceptance criteria and a file list, a read-only impact analysis, a scoped build step, and an evidence-first debug pass
• A plan-scope check: one git command that shows every file the agent touched outside the approved plan
• Three mode-switching patterns, and the signal that tells you to switch
• Recovery steps for the five ways mode choice goes wrong

Which Cursor mode fits the task?

A mode is a write permission, not a personality. The question to ask is not “which mode is smartest?” but “should the agent be allowed to change files yet?”

Your situation	Mode	What the agent may change	Leave the mode when
The change spans several files, or you could not write its acceptance criteria right now	Plan Mode	Nothing in the code; it produces a plan	You approved a plan that names every file and a test per criterion
You need to understand code, trace a flow, or size a change	Ask mode if your picker offers it; otherwise Plan Mode with “do not edit” in the prompt	Nothing	You can state the change in one sentence and list the files
You know exactly what to build and how it will be checked	Agent mode	Files and terminal commands, within your run mode	The verify command passes and the diff stays inside the plan
A bug reproduces but reading the code does not explain it	Debug Mode if your picker offers it; otherwise Agent mode limited to tests and logging	Instrumentation and tests only, until the cause is proven	A log line or failing test confirms one hypothesis

Two consequences follow from the table. First, Agent mode is the right default only for tasks that are already specified. Second, the planning and investigation modes produce an artifact you can check (a plan, a list of affected files), which is much cheaper to review than a 14-file diff.

Plan the change in Plan Mode

Plan Mode, in Cursor’s words, “creates detailed implementation plans before writing any code” (Cursor’s Plan Mode page, verified 28 August 2026). The agent reads the codebase and returns a plan before anything is built; the prompt below also makes it ask you its open questions first.

1. Commit or stash your work, so git diff later shows only the agent’s changes.
2. Open a new chat and switch the mode picker to Plan Mode. Paste the prompt below with your ticket text.
3. Answer the agent’s questions. A question you cannot answer is a gap in the ticket, so take it to whoever owns the ticket rather than letting the agent guess.
4. Ask for changes until every acceptance criterion maps to a test and every file the change will touch is listed. Have the agent drop steps you do not want.
5. Ask the agent to save the accepted plan and its file list to the repository before the first edit, so the build steps and the scope check have something to point at. Commit the saved plan, then record the base you will compare against with PLAN_BASE=$(git rev-parse HEAD). Run echo "$PLAN_BASE" > docs/plans/rate-limit.base as well, so the value survives a new terminal.

Copy-paste prompt: plan with acceptance criteria and a file list (Plan Mode)

Plan this change. Do not edit any file yet.

Ticket:
Add per-API-key rate limiting to the public REST API: 100 requests per minute
per key, a 429 response with a Retry-After header when exceeded, and no limit
on GET /health. Limits must survive a restart of one instance.

Before proposing anything, read how existing middleware is structured in
src/middleware/ and how configuration is loaded, and tell me which store the
counters should live in and why.

Your plan must contain:
1. Acceptance criteria, numbered, each one testable.
2. For each criterion, the test that proves it (file path and test name).
3. Numbered build steps. Each step leaves the test suite green and is small
   enough to review with `git diff --stat`.
4. A "## Files" section listing every file the change will create or modify,
   one path per line.
5. Out of scope: what this change deliberately does not do.
6. Open questions: ask me up to three before you finish.

When I approve, save the plan to docs/plans/rate-limit.md and the file list
alone to docs/plans/rate-limit.files, one path per line.

Review the plan, not the code that does not exist yet. A plan is ready when it passes four checks: every criterion has a named test; the file list contains nothing you did not expect; the out-of-scope list says what you would otherwise have had to reject in review; and no step depends on a library or helper the agent has not shown you in the codebase. A plan that fails one of these costs one message to fix now and a revert later.

The same idea exists in the sibling tools: Claude Code starts in plan mode with --permission-mode plan (checked against claude --help, v2.1.283) and Codex has /plan. See feature planning in Claude Code and planning in Codex. For the tool-neutral version of the plan contract, see the build stage of the lifecycle.

Investigate without edits before you build

Some tasks are not ready for a plan because you do not yet know the blast radius. Use a read-only pass: Ask mode if your mode picker offers it, or Plan Mode with an explicit instruction not to edit. The output you want is a list you can check, not an essay.

Copy-paste prompt: read-only impact analysis (Ask mode or Plan Mode)

Do not edit any file. This is analysis only.

I want to replace `name: string` on the User type with `firstName: string`
and `lastName: string`.

1. List every file that reads or writes `user.name`, the User type, or a
   serialized `name` field (API responses, database columns, fixtures,
   snapshots). Give the file path and line for each.
2. Mark each hit as: compile error (TypeScript catches it), runtime-only
   (the compiler will not catch it), or external contract (API consumers,
   stored data, analytics events).
3. List the tests that currently cover each runtime-only and external hit,
   and say which hits have no test at all.

End with the three riskiest hits and why.

The classification in step 2 is what makes the answer useful. Compile errors verify themselves once the type changes; runtime-only and external-contract hits are where a plausible diff breaks production. Hits with no test are the tests you write first. If the agent misses code you know exists, point it at the folder with an @ mention and check the codebase index; context management in Cursor covers diagnosing that.

Build in Agent mode, one plan step at a time

Agent mode reads and edits files, runs terminal commands, and iterates. That power is only safe when the agent can check its own work, so two things must be in place before you hand it a plan:

• A verify command that runs types, lint, and tests in one call, for example npm run verify.
• A run mode that lets the agent run that command without asking, while destructive commands still stop for you. Cursor groups this under run modes; essential configuration sets up the command allowlist, Auto-review, and a hook that re-runs the gate when the agent finishes.

Then execute the plan one step per prompt. When a step finishes with a green verify command, commit it yourself. The commit is a rollback point that does not depend on the editor.

Copy-paste prompt: execute one plan step (Agent mode)

Implement step 2 of @docs/plans/rate-limit.md and nothing else.

Rules:
- Only modify files listed in @docs/plans/rate-limit.files. If you need a
  file that is not listed, stop and tell me which file and why.
- Write the tests named for this step first and run them. Show me that they
  fail for the expected reason before you implement.
- Then implement until `npm run verify` passes. Do not change, skip, or
  delete existing tests to get there.
- Follow the middleware structure in @src/middleware/auth.ts.

When done, report: the tests you added, the output summary of
`npm run verify`, and `git diff --stat`.

Agent mode works best on a task that touches a handful of files and already has its acceptance criteria. It works worst when the task needs business rules nobody has written down, because the agent fills the gap with a guess that compiles. If a step turns out to be bigger than planned, go back to Plan Mode and split it rather than letting Agent mode improvise.

Debug with runtime evidence, not guesses

For a bug that reproduces but that reading the code does not explain (a race, a timing issue, an intermittent 500), the fastest path is evidence first and edits second. Cursor has described Debug Mode as automating this loop: it proposes hypotheses, adds log statements, asks you to reproduce the bug, and fixes from what the logs show (not re-checked on 26 September 2026; use it only if your picker offers it). The prompt below does the same in Agent mode in any build, and keeps the instrumentation easy to find and remove.

Copy-paste prompt: evidence-first debugging (Debug Mode or Agent mode)

Checkout fails intermittently: about 1 in 5 attempts returns 500 with
"Cannot read properties of undefined (reading 'price')". It happens only when
the user has items in both the wishlist and the cart. Code:
@src/services/checkout.ts and @src/services/cart.ts.

Do not fix anything yet.
1. Give me up to three hypotheses, each with the observation that would
   rule it out.
2. Add log statements that distinguish them. Prefix every line you add with
   `// DEBUG-CHECKOUT` so I can remove them with one search.
3. Write a test that reproduces the failure, and tell me exactly how to
   reproduce it by hand as well.
Stop and wait for my logs.

After you paste the captured logs back, ask for one fix aimed at the confirmed cause, with the reproducing test as its proof. The full workflow, including git bisect run for regressions and recovery from the fix-break-fix loop, lives in AI-assisted debugging in Cursor.

When should you switch modes mid-task?

Switch when the task’s uncertainty changes, not when you get impatient. Three patterns cover most sessions.

Pattern	Use it for	The signal to switch
Plan → Agent → (Plan)	A feature that spans several files	You approved the plan, so move to Agent. Return to Plan Mode when a step needs a file the plan did not list
Agent → Debug or instrumented Agent → Agent	A bug that survived one fix attempt	The first fix did not turn the reproducing test green. Stop editing and gather evidence
Read-only → Agent, repeated in small loops	Small changes in unfamiliar code	You can name the file and the one-line intent. Go back to read-only when you cannot

One rule holds across all three: after a switch, restate the goal and point at the saved plan with an @ mention. Do not rely on the conversation to remember a plan it produced 40 messages earlier. A saved docs/plans/*.md file is the same in every mode and every chat.

When you want two approaches at once, for example two plans or a plan and a spike, run them as separate agents rather than switching back and forth in one chat. The Agents Window and Projects covers running agents side by side, and worktrees keep their edits apart. If you drive Cursor’s agent from code, @cursor/sdk accepts mode: "plan" or mode: "agent" when you create an agent; see the Cursor SDK.

How do you verify the result without reading every diff?

Each mode ends with evidence, and the evidence is what you and the reviewer check. Reading the full diff becomes the exception you reserve for the files the evidence flags.

Mode	Evidence that ends it	Who signs off
Plan Mode	A saved plan where every acceptance criterion names a test, plus a file list	The developer, and the tech lead for changes to shared contracts
Read-only pass	A classified list of hits with file paths and the untested ones marked	The developer
Agent mode	Tests written first and shown failing, npm run verify green, diff inside the file list	CI on the pull request, then the reviewer
Debug	A log line or test that confirms one hypothesis, and the same test green after the fix	The developer; the reviewer checks the test, not the fix

The scope check is the cheapest of these and the one most often skipped. Run it in a terminal before you open the pull request:

# Files changed since the plan was committed that the plan did not list,
# including uncommitted edits and new untracked files.
PLAN_BASE=${PLAN_BASE:-$(cat docs/plans/rate-limit.base)}
{ git diff --name-only "$PLAN_BASE"; git ls-files --others --exclude-standard; } \
  | sort -u | grep -v '^docs/plans/' | grep -vxF -f docs/plans/rate-limit.files

Empty output means the agent stayed inside the approved plan. Any path it prints is either a legitimate gap in the plan, which you add to the file list and explain in the pull request, or drift, which you revert. Either way you read that file, and only that file, closely. For the pull request itself, Bugbot reviews the diff for bugs and security issues, and CI re-runs the same verify command so the result does not depend on the agent’s report. The broader argument for reviewing evidence instead of diffs is in reading evidence instead of code.

What breaks when you pick the wrong Cursor mode?

Agent mode edits far more files than expected. The task was not specified, so the agent specified it by editing. Recovery: discard the edits with git restore ., then preview new untracked files with git clean -nd and remove them with git clean -fd (or git reset --hard "$PLAN_BASE" if you already committed steps you now reject), or roll back with a checkpoint; then start a new chat in Plan Mode, and do not return to Agent mode until the plan has a file list. Do not try to repair a wrong 14-file diff with follow-up prompts; a refined plan and a fresh run are almost always faster.

The plan is vague. Plans mirror their input: “add authentication” produces steps like “implement auth logic”. Recovery: paste the ticket’s acceptance criteria, name the files or folders with @, and require the numbered sections from the plan prompt above. If the agent still cannot name tests, the acceptance criteria are not testable yet, which is a ticket problem, not a mode problem.

A read-only pass edits a file. The chat was in Agent mode, or the prompt invited a fix. Recovery: check git status, restore any changed file, confirm the mode picker before you send, and keep “Do not edit any file” as the first line of every investigation prompt.

Debug instrumentation stays in the code. Log lines added during a hunt reach the pull request. Recovery: search for the prefix you asked for (DEBUG-CHECKOUT above), remove every hit, and add a lint rule or a CI grep that fails the build on the prefix, so the next hunt cannot leak either.

The agent forgets the plan after a switch. Long chats lose early context, and the agent rebuilds the plan from memory with small differences. Recovery: point at @docs/plans/*.md in every build prompt, start a new chat for each plan step if the conversation is long, and let the scope check catch what slips through.

Where to go next with Cursor’s modes

Essential configuration The verify command, run mode and gate-rerun hook that make Agent mode safe to leave running.

Your first feature with Cursor's agent The Plan-then-Agent loop applied end to end, with a test per acceptance criterion.

Checkpoints and branching Rollback points for when Agent mode goes somewhere you did not plan.

Large codebase strategies Why planning and read-only passes matter more as the repository grows.

Custom rules and templates Put the plan format and the build-step rules into project rules so every chat starts with them.

AI-assisted debugging in Cursor The full evidence-first debugging workflow behind the Debug pattern on this page.