Mastering Cursor’s Plan Mode: A Step‑by‑Step Guide

Cursor Plan Mode Overview

Cursor Plan mode implements a structured task‑management workflow: the AI first creates a detailed plan, waits for user confirmation, then executes code changes while tracking each step.

Core Characteristics

Separate planning and execution: AI drafts a plan and only proceeds after the user approves it.

Task tracking: A todos list shows the status of each task ( pending → in_progress → completed).

Risk reduction: Users review the plan before any modifications, preventing large‑scale mistakes.

Traceability: Every change is linked to a specific plan step, aiding maintenance.

Typical Scenarios

Complex requirements spanning multiple files.

Massive feature hiding or replacement.

Explicit user request for “plan before action”.

Multiple implementation options that need selection.

Incomplete requirement information that requires clarification.

Tool Set

The internal tools are invoked automatically by the AI; users interact only with natural language.

ask_question – Clarify Requirement

Used when the requirement is ambiguous, when multiple implementations exist, or when technical details (e.g., API availability) need confirmation.

User simply answers the AI’s question; no special syntax is required.

create_plan – Generate Structured Plan

Creates a JSON‑like plan with the following schema:

{
  "name": "plan-name",
  "overview": "one‑sentence summary",
  "steps": ["Step 1 – specific operation", "Step 2 – specific operation", "..."],
  "todos": [
    {"id":"todo-1","content":"task description","status":"pending"},
    {"id":"todo-2","content":"task description","status":"pending"}
  ]
}

The AI shows the overview and steps for user confirmation.

todo_write – Task Management

Updates task status ( pending → in_progress → completed).

Can add new tasks during execution by setting "merge": true and providing additional todos entries.

{
  "merge": true,
  "todos": [{"id":"todo-new","content":"new task description","status":"pending"}]
}

Interaction Pattern

User: I want to hide some fields in the board‑info module, please draft a plan. AI: [automatically calls create_plan and displays the plan] User: You may start execution. AI: [automatically calls todo_write to update task status and begin modifications]

If the requirement is unclear, the AI calls ask_question first:

User: I need to replace order & after‑sale functions but I’m not sure the API is ready. AI: [calls ask_question ] AI: Do the order & after‑sale and offline revenue APIs exist, or should we use mock data? User: Use mock data. AI: [creates a plan that includes mock data]

Concrete Example: Hide Fields in Board‑Info Module

Goal: Comment out selected UI elements across several Vue components without deleting code.

Scope:

Search page – hide insurance options, rate queries, account‑type columns, etc.

User detail page – hide nickname, identity, account balance, collaboration tabs, service‑record section.

Order detail page – hide service person, reward coupons, related‑personnel tabs.

Order info page – hide product entry, basic info, continuous‑insurance, auto‑deduction sections.

Constraint: Only comment out code; no deletions.

Full Plan JSON

{
  "name": "legal-affairs-hide-fields",
  "overview": "Hide specified functions and fields in the info module via comments without deleting code.",
  "steps": [
    "Step 1 – Search page: comment out insurance options, rate queries, account‑type columns in search‑home.vue",
    "Step 2 – User detail: comment out nickname/identity/account‑balance fields, collaboration tabs, service record section in user‑detail.vue",
    "Step 3 – Order detail: comment out service person, reward coupon columns in order‑detail‑header.vue, and related‑personnel tabs in order‑detail.vue",
    "Step 4 – Order info: comment out product entry, basic info, continuous‑insurance, auto‑deduction sections in order‑info.vue",
    "Step 5 – Verify & test: run read_lints to ensure comment syntax is correct"
  ],
  "todos": [
    {"id":"todo-search","content":"Comment out unnecessary options in search‑home.vue"},
    {"id":"todo-user-detail","content":"Trim user‑detail.vue as specified"},
    {"id":"todo-order-detail","content":"Adjust order‑detail components"},
    {"id":"todo-order-info","content":"Simplify order‑info.vue"},
    {"id":"todo-verify","content":"Run lint verification"}
  ]
}

Execution Flow

AI: I have created a Plan with the following steps and todos:
- Step 1: Search page adjustment
- Step 2: User detail trimming
- Step 3: Order detail adjustment
- Step 4: Order info simplification
- Step 5: Verify & test
Todos:
- todo-search (pending)
- todo-user-detail (pending)
- todo-order-detail (pending)
- todo-order-info (pending)
- todo-verify (pending)
Can I start execution?

After user approval, each todo is processed sequentially:

AI: Starting todo-search
todo_write({"id":"todo-search","status":"in_progress"})
// read_file("search-home.vue")
// comment out insurance options, rate queries, etc.
 todo_write({"id":"todo-search","status":"completed"})
... (repeat for remaining todos)

Mid‑Execution Adjustments

Small Adjustments

Add a new todo without disrupting the current flow:

todo_write({
  "merge": true,
  "todos": [{"id":"todo-fix-table","content":"Adjust table width to remove scrollbars","status":"pending"}]
})

Large Adjustments

If the overall direction changes, create a new plan.

Post‑Completion Optimization

Iterative Tweaks

For minor performance or style improvements, add new todos to the existing plan.

New Optimization Plan

{
  "name": "legal-affairs-optimization",
  "overview": "Improve performance and code quality of the info module.",
  "steps": [
    "Step 1 – Performance: virtual scroll for large tables",
    "Step 2 – Refactor: extract common components",
    "Step 3 – UX: add loading states"
  ],
  "todos": [
    {"id":"todo-performance","content":"Optimize table rendering"},
    {"id":"todo-refactor","content":"Extract common components"},
    {"id":"todo-ux","content":"Add loading indicators"}
  ]
}

Common Questions

Do I need to type tool‑call code?

No. Describe the requirement in natural language; the AI selects the appropriate tool.

How does the AI choose a tool?

Keywords such as “draft a plan” trigger create_plan; ambiguous requirements trigger ask_question.

Can I see the tool calls?

Tool calls appear as JSON‑like snippets in the AI’s response, but the user mainly sees the plan and status updates.

How to monitor progress?

Inspect the todos list; each entry shows its current status.

Best‑Practice Checklist

Make the plan concrete: include file paths and exact operations.

Keep todos atomic: each todo should be independently executable.

Execute sequentially: finish one todo before starting the next.

Update status promptly: move from pending to in_progress to completed.

Adjust flexibly: small issues are added as new todos; major scope changes merit a new plan.