SOP-007: Agent Modes

Document Control

Field	Value
SOP ID	SOP-007
Version	1.0
Status	Active
Last Updated	2024-12

Purpose

This SOP covers the four Agent modes in Cursor: Agent, Ask, Plan, and Debug. Each mode is optimized for different tasks.

Scope

• Understanding each mode's purpose
• Switching between modes
• Best practices for mode selection

Prerequisites

• Cursor installed and configured
• Familiarity with Agent Chat (SOP-006)

---

Procedure

Mode Overview

Mode	Purpose	Tools	Best For
Agent	Default for coding	All tools enabled	Features, refactoring
Ask	Read-only exploration	Search tools only	Learning, questions
Plan	Creates plan first	All tools	Complex features
Debug	Hypothesis + testing	All + debug server	Tricky bugs

Step 1: Switch Modes

Quick Switch: Cmd+. / Ctrl+.

Or:

• Click mode dropdown in chat header
• Press Shift+Tab from chat input to rotate

---

Mode: Agent (Default)

Purpose: Complex features, refactoring, multi-file changes

Tools Available: All (search, edit, terminal, MCP)

Best For:

• Implementing new features
• Refactoring code
• Multi-file changes
• Running tests and commands
• Installing dependencies

Workflow:

1. Describe what you want
2. Agent explores codebase
3. Agent makes changes
4. You review and approve

Example Prompts:

• "Add a dark mode toggle to the settings page"
• "Refactor the API layer to use async/await"
• "Create unit tests for the UserService class"

---

Mode: Ask

Purpose: Learning, planning, understanding code (read-only)

Tools Available: Search tools only (no editing)

Best For:

• Understanding unfamiliar code
• Learning how something works
• Planning before implementing
• Code review questions
• Architecture discussions

Key Benefit: No risk of unwanted changes

Workflow:

1. Ask questions about code
2. Agent searches and explains
3. No changes made to files
4. Switch to Agent mode to implement

Example Prompts:

• "How does the authentication flow work?"
• "Explain the data model for orders"
• "What would be the best approach to add caching?"

---

Mode: Plan

Purpose: Complex features requiring upfront planning

Tools Available: All (but focuses on planning first)

Workflow:

1. You describe the feature/change
2. Agent asks clarifying questions
3. Agent researches codebase
4. Agent creates detailed plan
5. You review/edit plan (virtual file)
6. Click "Build" to execute plan

Plans saved in: .cursor/plans/

Trigger: Shift+Tab from chat input or select from mode menu

Example Use Cases:

• Large feature implementation
• Architectural changes
• When you want to verify approach before coding

Plan Management:

• Plans open as virtual markdown files
• Click "Save to workspace" to store in .cursor/plans/
• Share plans with team
• Reference plans in future conversations

---

Mode: Debug

Purpose: Finding root causes of tricky bugs

Tools Available: All + debug server for log instrumentation

Debug Mode Workflow:

1. Explore & Hypothesize - Agent explores code, generates hypotheses
2. Add Instrumentation - Agent adds log statements, logs sent to local debug server
3. Reproduce Bug - Agent gives you steps to reproduce, you trigger the bug, logs are collected
4. Analyze Logs - Agent reviews runtime data, identifies root cause
5. Targeted Fix - Agent makes focused fix, often just a few lines
6. Verify & Cleanup - You verify fix works, Agent removes instrumentation

Best For:

• Bugs that can be reproduced
• Performance issues
• Memory leaks
• Race conditions

Example Prompts:

• "The login fails intermittently, help me debug"
• "This API call is slow, find the bottleneck"
• "Users report data loss during save, investigate"

---

Mode Selection Guide

If you're thinking...	Use
"I want to build a feature"	Agent or Plan
"I want to understand this code"	Ask
"I need to plan a complex change"	Plan
"Something is broken and I don't know why"	Debug
"Quick modification to existing code"	Agent
"Is my approach correct?"	Ask → then Agent

---

Custom Slash Commands

Create custom workflows with slash commands:

Create a command:

1. Open .cursor/commands/ in your project
2. Create a markdown file (e.g., learn.md)
3. Add instructions and tool limitations

Example /learn command:

# Learn Mode
Use only search tools (read file, codebase search, grep).
Do not make any edits or run terminal commands.
Explain concepts thoroughly with examples.

Example /refactor command:

# Refactor Mode
Focus on code quality improvements.
Preserve existing functionality.
Add or update tests for changed code.

---

Verification Checklist

• [ ] Can switch modes with Cmd+.
• [ ] Agent mode makes file changes
• [ ] Ask mode only reads, no changes
• [ ] Plan mode creates reviewable plan
• [ ] Debug mode adds instrumentation
• [ ] Custom slash commands work if created

Troubleshooting

Issue	Solution
Mode not switching	Refresh chat or restart Cursor
Plan not generating	Check network, may need more context
Debug logs not appearing	Verify debug server running
Wrong mode for task	Review mode selection guide above

See Also

• SOP-006: Agent Chat
• Workflow: Debugging
• Workflow: AI-Assisted Development