Agent Modes Deep Dive

Your PM just dropped a ticket that requires changes across the API layer, three React components, a database migration, and the test suite. You open Cursor, type a prompt into Agent mode, and 90 seconds later you are staring at a diff that touched 14 files — half of them wrong. The problem was not the prompt. The problem was using Agent mode for a task that should have started in Plan mode, moved through Ask mode for investigation, and only then been handed to Agent for execution.

Choosing the right mode is the single highest-leverage decision you make in every Cursor session.

What You’ll Walk Away With

• A clear decision framework for when to use Agent, Ask, Plan, and Debug modes
• Mode-switching patterns that produce better results than staying in a single mode
• Copy-paste prompts optimized for each mode
• Configuration settings for auto-run, auto-fix, and safe YOLO mode usage

The Four Modes

Mode	Purpose	Capabilities	Tools
Agent	Build features, fix bugs, refactor	Autonomous exploration, multi-file edits, terminal commands	All tools enabled
Ask	Understand code, plan work, explore	Read-only codebase search and explanation	Search tools only
Plan	Break down complex features	Creates detailed implementation plans, asks clarifying questions	All tools enabled
Debug	Find root causes of tricky bugs	Hypothesis generation, log instrumentation, runtime analysis	All tools + debug server

Switch between modes with Cmd+. (Mac) or Ctrl+. (Windows/Linux). You can also press Shift+Tab from the chat input to rotate through modes.

Agent Mode: Autonomous Multi-File Work

Agent mode is the default and the most powerful. It can read files, edit files, run terminal commands, search your codebase, and iterate until the task is done. Use it when you know what you want built and the scope spans multiple files.

The YOLO Mode Configuration

Enable auto-run for terminal commands so Agent can verify its own work without asking you to approve every npm test invocation. Go to Cursor Settings and enable auto-run with an allowlist:

Tip

Copy-paste prompt for configuring YOLO mode:

In your Cursor Settings, set the auto-run prompt to:

Run tests (vitest, jest, npm test), build commands (tsc, npm run build), linting (eslint, prettier), and file operations (mkdir, touch, cp) without asking. Never run destructive commands like rm -rf, git push --force, or DROP TABLE.

The key insight: Agent mode becomes dramatically more useful when it can run your test suite after making changes. Instead of generating code and hoping it works, Agent writes code, runs tests, sees failures, and iterates until tests pass — all without intervention.

When Agent Mode Shines

• Implementing a new feature that touches 3-10 files
• Refactoring an interface and updating all consumers
• Generating a complete test suite for existing code
• Fixing a bug when you already know which area of the codebase is involved

When Agent Mode Struggles

• You do not understand the codebase well enough to evaluate the output
• The change requires understanding subtle business logic that is not documented
• You need to touch more than 15-20 files (break it into smaller tasks)

Tip

Copy-paste prompt for test-driven Agent mode:

Implement a rate limiter middleware for our Express API.

1. Write tests first in src/middleware/__tests__/rate-limiter.test.ts covering: per-IP limiting, sliding window behavior, custom limits per route, and bypass for health check endpoints.
2. Implement the middleware in src/middleware/rate-limiter.ts.
3. Run the tests and fix any failures.
4. Repeat until all tests pass.

Follow the patterns in @src/middleware/auth.ts for middleware structure.

Ask Mode: Read-Only Exploration

Ask mode searches your codebase and provides answers without making any changes. It is the mode you should be using far more often than you probably are. The official Cursor docs recommend planning with Ask mode and implementing with Agent mode — and this pattern consistently produces better results than jumping straight into Agent.

The Planning-First Pattern

Before any complex change, open Ask mode and build understanding:

Tip

Copy-paste prompt for codebase exploration:

I need to add multi-tenancy to our application. Before I start:

1. How is our current authentication system structured? Trace the flow from login request to authenticated API call.
2. Which database tables currently have no tenant_id column?
3. Are there any shared services or singletons that would need to become tenant-aware?
4. What patterns do our existing multi-tenant tables use for data isolation?

Search the codebase thoroughly. I need specifics, not generalizations.

Ask Mode for Impact Analysis

Before making a breaking change, use Ask mode to understand the blast radius:

If I change the User interface to replace `name: string` with
`firstName: string` and `lastName: string`, what parts of the
codebase would break? List every file, function, and test that
references `user.name` or the User type.

Ask mode with a good question is 10x faster than grep-and-read. Use it to build context before you give Agent mode its instructions.

Plan Mode: Structured Breakdown for Complex Features

Plan Mode is the most underused mode in Cursor. It creates detailed implementation plans before writing any code. The agent researches your codebase, asks you clarifying questions, and generates a reviewable plan you can edit before building.

When to Use Plan Mode

• Features with multiple valid approaches where you want to evaluate options first
• Tasks that touch many files or systems and need careful sequencing
• Unclear requirements where you need to explore before understanding scope
• Architectural decisions where you want to review the approach before committing

The Plan-Then-Execute Workflow

1. Switch to Plan mode (Shift+Tab from chat input)
2. Describe your goal with whatever context you have — paste ticket descriptions, link to related files, mention constraints
3. The agent asks clarifying questions (answer them)
4. Review the generated plan — edit it, add missing steps, reorder priorities
5. Click “Build” to execute the plan in Agent mode

Tip

Copy-paste prompt for Plan mode:

Create a plan for adding Stripe subscription management to our SaaS application.

Context from our product ticket:
- Users should be able to subscribe to monthly or annual plans
- We need webhook handlers for payment events
- Existing user model is in @src/models/user.ts
- Current payment logic (one-time only) is in @src/services/payment.ts

Ask me up to 3 clarifying questions if anything is unclear. Search the codebase for existing payment patterns before proposing the plan.

Restarting from a Plan

When Agent builds something that does not match your intent, do not try to fix it through follow-up prompts. Revert the changes, refine the plan to be more specific, and run it again. This is almost always faster than debugging an incorrect implementation.

Debug Mode: Runtime Evidence Over Guesswork

Debug Mode is designed for bugs that are hard to reproduce or understand. Instead of immediately writing code, the agent generates hypotheses, adds temporary log statements, asks you to reproduce the bug, and uses the captured runtime information to pinpoint the exact issue.

When Debug Mode Beats Agent Mode

• Bugs you can reproduce but cannot figure out from reading the code
• Race conditions and timing issues
• Performance problems and memory leaks
• Regressions where something used to work and now does not

How Debug Mode Works

1. You describe the bug with as much detail as possible (error messages, stack traces, reproduction steps)
2. The agent explores relevant files and generates hypotheses about potential root causes
3. The agent adds instrumentation (log statements) at strategic points
4. You reproduce the bug following the agent’s specific instructions
5. The agent analyzes the captured logs and identifies the root cause
6. The agent makes a targeted fix — often just a few lines — based on runtime evidence
7. You verify the fix and the agent removes all instrumentation

Tip

Copy-paste prompt for Debug mode:

The checkout process fails intermittently -- about 1 in 5 attempts returns a 500 error. The error only happens when users have items in both their wishlist and cart.

Expected behavior: Checkout completes successfully regardless of wishlist contents.
Actual behavior: Server returns 500 with "Cannot read properties of undefined (reading 'price')" in the logs.

The relevant code is in @src/services/checkout.ts and @src/services/cart.ts. I can reproduce by adding 3+ items to wishlist, then adding 2 items to cart, then clicking checkout.

Mode-Switching Patterns

The most effective Cursor users do not stay in one mode. They switch modes as the nature of their work changes within a single task.

Pattern: Ask, Plan, Agent

The gold standard for complex features:

1. Ask mode — Understand the current architecture and identify constraints
2. Plan mode — Create a detailed, reviewable implementation plan
3. Agent mode — Execute the plan with auto-run enabled

Pattern: Agent, Debug, Agent

For bugs that resist a first fix attempt:

1. Agent mode — Attempt the fix based on your understanding
2. Debug mode — When the fix does not work, switch to Debug for runtime analysis
3. Agent mode — Implement the targeted fix identified by Debug

Pattern: Ask, Agent (Iterative)

For incremental feature development:

1. Ask mode — “How does our routing work? Show me the middleware chain”
2. Agent mode — “Add authentication middleware following the pattern in @src/middleware/cors.ts”
3. Ask mode — “What did the agent just change? Did it handle the edge case where the token is expired?”
4. Agent mode — “Add expired token handling with a 401 response and refresh token flow”

When This Breaks

Agent mode edits too many files. This happens when the prompt is too broad. Break large tasks into pieces. Instead of “add authentication to the API,” try “add JWT verification middleware to the /api/users routes only.”

Ask mode cannot find relevant code. Make sure your codebase is indexed (check the indexing indicator in the bottom status bar). If indexing is complete and Ask still misses things, use @file and @folder mentions to point it at specific locations.

Plan mode plan is too vague. Provide more concrete context: paste ticket descriptions, reference existing files with @, and specify constraints explicitly. A vague input produces a vague plan.

Debug mode instrumentation does not capture the issue. Provide more detailed reproduction steps. If the bug is intermittent, tell Debug mode to add more granular logging and reproduce multiple times.

What’s Next

• Checkpoints and Branching — Safe experimentation strategies for when Agent mode makes changes you want to undo
• Large Codebase Strategies — Mode selection becomes even more critical at scale
• Custom Rules and Templates — Encode mode-specific instructions into reusable rules