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

URL: https://developertoolkit.ai/en/cursor-ide/build/agent-modes-deep-dive/
Description: Pick the right Cursor agent mode for each phase: Plan Mode before edits, Agent mode against gates, and read-only or debug passes when you need evidence.

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. Cursor also has a read-only Ask mode and a Debug mode for bugs that need runtime evidence (four modes in Cursor's docs, checked 2026-10-12). The right mode depends on how well the task is specified.

**Documentation freshness**

**Covers:** the Cursor 3.x line; the current release on 2026-10-12 is Cursor 3.24 (2026-10-09, Cursor's release notes). Cursor's docs and help list four modes: Agent, Ask, Plan and Debug. Ask is read-only, Plan edits only after you approve the plan, and Debug is for tricky bugs that need runtime evidence. Shift+Tab cycles through the modes, and each mode starts a fresh context window (checked 2026-10-12). Plan Mode and Agent mode were first verified against Cursor's docs on 28 August 2026. Cursor's own `@cursor/sdk` package still exposes only two conversation modes, `agent` and `plan`: read from 1.0.32 on npm on 26 September 2026, and unchanged in 1.0.37 (2026-10-07, checked 2026-10-12). 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 | Nothing; Ask mode is read-only | 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, or 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](https://cursor.com/docs/agent/plan-mode), 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)**

```text
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](/en/claude-code/plan/feature-planning/) and [planning in Codex](/en/codex/plan/). For the tool-neutral version of the plan contract, see [the build stage of the lifecycle](/en/method/lifecycle/build/).

## 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, 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)**

```text
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](/en/cursor-ide/quick-start/context-management/) 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](/en/cursor-ide/quick-start/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)**

```text
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 (the description of its loop was not re-checked; the mode itself is listed in Cursor's docs, checked 2026-10-12). 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)**

```text
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](/en/cursor-ide/test/bug-hunting/).

## 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: Cursor's help says each mode starts a fresh context window (checked 2026-10-12). 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](/en/cursor-ide/build/agents-window/) 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](/en/cursor-ide/automate/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:

```bash
# 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](/en/cursor-ide/ship/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](/en/ladder/evidence-not-diffs/).

## 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](/en/cursor-ide/build/checkpoints-branching/); 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.** Switching modes starts a fresh context window (Cursor's help, checked 2026-10-12), and long chats lose early context besides, so 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](/en/cursor-ide/quick-start/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](/en/cursor-ide/quick-start/first-feature/) — The Plan-then-Agent loop applied end to end, with a test per acceptance criterion.
- [Checkpoints and branching](/en/cursor-ide/build/checkpoints-branching/) — Rollback points for when Agent mode goes somewhere you did not plan.
- [Large codebase strategies](/en/cursor-ide/build/large-codebase-strategies/) — Why planning and read-only passes matter more as the repository grows.
- [Custom rules and templates](/en/cursor-ide/automate/custom-rules-templates/) — Put the plan format and the build-step rules into project rules so every chat starts with them.
- [AI-assisted debugging in Cursor](/en/cursor-ide/test/bug-hunting/) — The full evidence-first debugging workflow behind the Debug pattern on this page.