Modes: Ask, Plan, Agent, and Debug

So far you’ve let Cursor run wherever it landed by default — you opened the chat, typed a request, and it edited files and ran commands without you thinking about how much freedom it had. On a one-line fix that’s fine. The moment a change reaches into code a dozen call sites depend on, it stops being fine, and the thing that controls it is the mode.

A mode is not a different model and it’s not a different chat. It’s the same Cursor reading the same project at a different posture — how far it’s allowed to go before you look. Cursor gives you a small set of named postures and one keystroke to move between them, and the skill this chapter teaches isn’t the keystroke. It’s the judgment: given what’s in front of you, which posture does this task actually want?

The mode picker

You switch modes two ways: Shift+Tab cycles through them in the chat input, or you pick one from the mode dropdown next to the input box.

The picker holds these:

• Ask — read-only Q&A. It answers and explains; it does not change your files.
• Agent — full execution: it plans, edits across whatever files it judges relevant, runs commands, and self-corrects until the task is done. In practice this is the mode you’ll sit in most.
• Plan — clarify, research, then hand you an editable markdown plan before any code is written.
• Debug — a later, fourth mode (added in the 2.2 release) focused on reproducing and fixing a failure rather than implementing a feature.

The reason there’s a chord for this and not just a setting buried in preferences is that you’re meant to switch often — sometimes several times inside one piece of work. The natural rhythm is to Ask to understand unfamiliar code, Plan the approach, then drop into Agent to build it. That’s one task climbing the ladder of latitude as your confidence grows, not three separate conversations.

Ask: understand before you touch

Reach for Ask when the thing you need is knowledge, not a change. It’s read-only by construction — it will trace code, explain a flow, and answer “where does X happen,” but it won’t edit a file or run a command that mutates state. That guarantee is the point: you can point it at code you’re afraid of and know nothing will move.

The tell for Ask is that you can’t yet name the change you want. You’re still asking what is this and where does it live:

ask ›
> where does budgetcli decide a transaction is allowed to post
  against a budget? is the check in this repo, or somewhere shared?

  The budget gate is in budget/guard.go, but the rule it
  enforces — the spend-limit threshold — isn't local. guard.go calls
  policy.AllowsSpend(txn), and that function lives in the
  shared `budget-policy` module, imported by six other services.
  Nothing here changes the threshold; it only reads it.

That answer just changed the shape of the job. What looked like a one-repo edit is actually a change to a shared module a half-dozen services depend on — a high blast-radius change wearing a low-effort disguise. You learned that for free, in a mode that couldn’t have broken anything while you learned it. That’s what Ask is for.

Agent: full execution

Agent is the right posture for most work, and it’s the mode you’ll spend the most time in. You describe an outcome; it does the whole loop — reads what it needs, edits across however many files it decides are relevant, runs tests, reads the failures, and fixes them — surfacing risky commands for approval as it goes rather than stopping to plan with you first.

Agent is the correct posture when the change is contained and you’d rather review a finished diff than co-author the approach. A gnarly algorithm that lives entirely in one file you own is a perfect Agent task even though it’s hard — the difficulty is real but the blast radius is small, so letting it run and reviewing the result is cheaper than narrating every step.

agent ›
> the retry backoff in feed/fetcher.go is linear; make it exponential
  with jitter, capped at 30s, and keep the existing max-attempts
  behaviour.

  ⏵ Read   feed/fetcher.go, feed/fetcher_test.go
  ⏵ Edit   feed/fetcher.go   → exponential backoff + jitter, 30s cap
  ⏵ Run    go test ./feed/...
    • ok  0.18s
  Done. Backoff now doubles per attempt with ±20% jitter, capped at
  30s; max-attempts unchanged. Tests pass.

What you’re trusting Agent with is latitude, not correctness — you still review the diff. The judgment is matching that latitude to the stakes, which is exactly where Plan comes in.

Plan: clarify, research, then a plan you can edit

Plan is the posture for a change big enough that letting Agent start editing on its first instinct is how you get a confident rewrite of the wrong thing. Instead of jumping to edits, Plan runs a deliberate sequence before a single line is written.

The flow:

1. It asks clarifying questions. Plan doesn’t assume the spec; it pulls the ambiguity out of you first.
2. It researches the codebase — read-only. It reads and greps to ground the plan in the real code, without touching anything.
3. It writes the plan as an editable markdown file. Not a chat message you skim and lose — a .md artifact you can open, argue with, and rewrite.
4. You edit the plan inline, then click to build from it.

plan ›
> add a second-approver requirement: transactions above a configurable
  threshold can't post until a second user approves them.

  Before I plan this, a few questions:
  • Should the threshold be per-org or global?
  • Does "approve" need an audit record, or just a status flip?
  • Is the second approver any user, or a specific role?

> per-org threshold; yes, every approval must be audited; second
  approver must hold the "budget-admin" role.

  ⏵ Read  budget/guard.go, budget-policy/policy.go,
          audit/log.go, models/transaction.go       (gathering context)

  Wrote plan to second-approver-plan.md:
    1. Add PerOrgThreshold to budget-policy (shared module — bump
       minor, coordinate the six importers).
    2. Add an Approval record + audit entry in audit/log.go.
    3. Gate guard.go on role "budget-admin".
    4. Migration for the transaction approval-state column.
  Edit the plan, then build when you're ready.

Two things in that transcript are the whole reason Plan exists. The clarifying turn caught three decisions you’d otherwise have discovered as bugs. And the research stage is about gathering context, not shipping changes — it reads and greps your actual code to ground the plan, and the only artifact it produces is the plan itself.

Where the plan is saved

Plans are saved by default in your home directory — it’s yours, a personal artifact, not part of the repo. When you want the plan in the repo so teammates (or a PR) can see it, click “Save to workspace”, which moves it into the project.

Plan with one model, build with another

The detail that makes Plan more than a speed bump, shipped in Cursor 2.0: you can create your plan with one model and build it with another. Point a frontier reasoning model at the design — where the cost of a bad call is highest — and then hand the approved, written-down plan to a faster, cheaper model to execute. The plan is a markdown artifact, so the second model doesn’t need the first model’s reasoning context; it needs the plan, which is sitting right there.

This is also where the blast-radius rule pays off. The second-approver feature above touches the shared budget-policy module six services import — high blast radius, easy to get subtly wrong, expensive to undo. That’s precisely the task that earns the clarify-research-plan ceremony. The exponential-backoff change earlier did not. Difficulty isn’t the signal; who a mistake hurts, and how hard it is to reverse is.

Debug: the later fourth mode

Debug is the newest posture, added after the other three. Where Agent’s instinct is to implement a feature and Plan’s is to design one, Debug’s job is to reproduce and fix a tricky bug — reach for it when something is already broken and a normal Agent pass hasn’t found the cause.

Note what Debug actually does, because it isn’t a read-only “tell me why” mode. Its loop is hands-on:

1. It generates several hypotheses about what’s going wrong.
2. It instruments your code with logging statements to test those hypotheses — meaning it edits files before the root cause is known, planting probes rather than waiting until it’s certain.
3. You reproduce the bug so it can collect the runtime logs those probes emit.
4. It reads the logs, isolates the cause, and ships a targeted fix — typically a precise two- or three-line modification — then removes the instrumentation it added.

So Debug both edits to diagnose and delivers the fix. The contrast with Agent isn’t “Debug won’t touch your code” — it will, twice. It’s that Debug is built around the reproduce-instrument-fix cycle for bugs that resist a straight-ahead Agent attempt, rather than implementing new behaviour.

The same modes from the CLI

Everything in this chapter is the GUI editor. Cursor’s CLI — invoked as agent today, with cursor-agent kept as a legacy alias you’ll still see in mixed sources — exposes the same posture switch as slash commands — /plan to enter Plan mode and /ask to enter Ask mode from the terminal — so the judgment you’re building here carries straight over to headless and CI runs. The CLI’s slash-command reference lists /plan and /ask but no /agent or /debug mode-switch command, so those two are the modes you steer explicitly from the terminal.

We cover the CLI properly in its own chapter — for now, the thing to carry forward is that modes aren’t a GUI gimmick. They’re a posture that travels with you into the terminal.

The skill, restated

The four modes aren’t four features to memorize. They’re a single dial — how much latitude does this task deserve before I look? — with four detents:

• Ask when you don’t yet know the change. Read-only; zero risk.
• Agent when the change is contained and you’d rather review a finished diff.
• Plan when a mistake reaches past the file in front of you — clarify, research, write it down, edit it, then build.
• Debug when something is already broken and a normal Agent pass can’t crack it — let it instrument, reproduce, and fix.

Shift+Tab makes moving between them nearly free, which is the whole point: you’re meant to switch deliberately, often, mid-task. The person who’s merely installed Cursor leaves it in Agent and hopes. The person who’s good with it feels which detent a task is asking for before they type a word.