#Plan Mode

Plan Mode writes a reviewable implementation plan before any code. Agent researches the repo, asks clarifying questions, and waits until you approve the build. Official page: Plan Mode.

#How to enter

Press Shift+Tab in the Agent input to rotate modes (desktop is usually Agent / Plan / Ask). You can also use the mode dropdown. Cursor sometimes suggests Plan Mode when your text looks like a complex task.

The CLI matches the editor:

agent --plan
# or
agent --mode=plan

In an interactive CLI session use /plan, or the same Shift+Tab shortcut.

#The official loop

1. Ask questions until the requirement is clear
2. Research the codebase for relevant files
3. Write a full implementation plan
4. You review / edit it in chat or as markdown
5. Build when you are ready

Plans are saved under your home directory by default. Save to workspace moves the file into the repo for sharing and later reference.

flowchart TD
  A[Shift+Tab into Plan] --> B[Clarifying questions]
  B --> C[Search / read the repo]
  C --> D[Editable plan]
  D --> E{Approve?}
  E -->|No| B
  E -->|Yes| F[Build: edits / commands]
  F --> G[Review diff]
  G --> H{Matches the plan?}
  H -->|No| I[Revert + tighten the plan]
  I --> F
  H -->|Yes| J[Commit]

#When to use it (and when not)

Officially best for:

• Complex features with several valid approaches
• Work that touches many files or systems
• Unclear requirements that need scoping first
• Architecture you want to review before coding

Quick edits or tasks you have done many times can stay in normal Agent. Plan Mode on a one-line copy change only adds round-trips.

Rule of thumb:

#An opener prompt

Put a definition of done and bans in so questions stay concrete:

Add a public /health JSON endpoint that returns { "ok": true }.

Constraints:
- Reuse the existing HTTP stack
- Do not change authentication
- Do not add a new framework

Ask me anything unclear. Research first. Produce a plan with:
- files you will touch
- test commands you will run
- risks

Do not edit files until I approve.

The plan should list paths and commands. If it is only adjectives (“add health checks elegantly”), send it back.

When you review:

1. Is the file list too wide (“refactor utils while we are here”)?
2. Are the test commands scripts the repo already has?
3. Are migrations / feature flags paired with a rollback?

Edit the plan markdown, or reply: Revise the plan: no new dependencies; add one unit test only.

#After a bad build: start from the plan

If the implementation drifts, do not stack ten “just fix it” prompts:

1. Revert files with a checkpoint or git checkout / git restore
2. Make the plan narrower and more specific
3. Build again

Officially this is often faster and cleaner than repairing a wandering Agent. The hard part is deciding what to change; then delegate implementation.

The queue still helps after you approve: enqueue Then run the existing lint and typecheck only. See Agent.

#Rules and MCP

Plan Mode uses Available Tools, including MCP. During research it can read issues, designs, or docs if those servers are on. Project rules still apply—put “plan first if more than N files change” in .cursor/rules instead of repeating it orally.

For teams, Save to workspace (for example docs/plans/) and link the file from the PR. That reviews better than a chat transcript.

#Short drill

1. Open any repo, press Shift+Tab.
2. Paste the /health prompt (rename to match the stack).
3. Answer clarifying questions.
4. Confirm the plan has not edited product code yet.
5. Either approve and review the diff, or discard the plan.

#Next

• Workflow with CLI Agents
• Practical Examples
• Quick Start