Cursor Best Practices

Cursor Best Practices

Best practices for working with Cursor to maximize productivity and code quality.

Core Principles

• Start with plans - Use Plan Mode (Shift+Tab) for complex tasks
• Manage context effectively - Let agent find context, start new conversations when needed
• Extend the agent - Use Rules for static context, Skills for dynamic capabilities
• Review carefully - AI-generated code needs review like human code

Key Workflows

• Test-driven development - Write tests first, iterate until passing
• Codebase understanding - Use agent to explore and learn codebases
• Git workflows - Automate common git operations with commands
• Parallel agents - Run multiple agents simultaneously for comparison

References

For detailed guidance, see:

• references/planning.md - Plan mode and starting with plans
• references/context.md - Managing context and conversations
• references/extending.md - Rules vs Skills, extending agent
• references/workflows.md - TDD, codebase understanding, git workflows
• references/reviewing.md - Code review strategies
• references/parallel-agents.md - Running agents in parallel

Managing Context

Let Agent Find Context

You don't need to manually tag every file in your prompt.

• Modern agents have powerful search tools and pull context on demand
• When you ask about "the authentication flow," agent finds relevant files through grep and semantic search
• Keep it simple: if you know the exact file, tag it. If not, agent will find it
• Including irrelevant files can confuse agent about what's important

Helpful Tools

• @Branch - Give agent context about what you're working on
• "Review the changes on this branch" or "What am I working on?" orient agent to current task

When to Start New Conversation

Start a new conversation when:

• You're moving to a different task or feature
• Agent seems confused or keeps making the same mistakes
• You've finished one logical unit of work

Continue the conversation when:

• You're iterating on the same feature
• Agent needs context from earlier in the discussion
• You're debugging something it just built

Long Conversations

Long conversations can cause agent to lose focus. After many turns and summarizations:

• Context accumulates noise
• Agent can get distracted or switch to unrelated tasks
• If effectiveness decreases, start a new conversation

Reference Past Work

When starting a new conversation, use @Past Chats to reference previous work rather than copy-pasting the whole conversation. Agent can selectively read from chat history to pull in only needed context.

This is more efficient than duplicating entire conversations.

Extending the Agent

Agent harnesses typically provide two main ways to customize agent behavior: Rules for static context and Skills for dynamic capabilities.

Rules: Static Context

Rules provide persistent instructions that shape how agent works with your code. Think of them as always-on context that agent sees at the start of every conversation.

Creating Rules

Create rules as markdown files in the appropriate rules directory (e.g., .cursor/rules/, .claude/rules/, .codex/rules/):

# Commands

- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker
- `npm run test`: Run tests (prefer single test files for speed)

# Code style

- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: `import { foo } from 'bar'`
- See `components/Button.tsx` for canonical component structure

# Workflow

- Always typecheck after making a series of code changes
- API routes go in `app/api/` following existing patterns

Best Practices for Rules

• Keep rules focused on essentials
• Reference files instead of copying contents
• Keep rules short to prevent them from becoming stale
• Start simple, add rules only when agent makes same mistake repeatedly

What to Avoid in Rules

• Copying entire style guides (use a linter instead)
• Documenting every possible command (agent knows common tools)
• Adding instructions for edge cases that rarely apply

Skills: Dynamic Capabilities

Agent Skills extend what agents can do. Skills package domain-specific knowledge, workflows, and scripts that agents can invoke when relevant.

Skills Include

• Custom commands: Reusable workflows triggered with / in agent input
• Hooks: Scripts that run before or after agent actions
• Domain knowledge: Instructions for specific tasks agent can pull in on demand

Skills vs Rules

• Rules: Always included, static context
• Skills: Loaded dynamically when agent decides they're relevant
• Skills keep context window clean while giving agent access to specialized capabilities

AGENTS.md

Simple markdown file for defining agent instructions. Place in project root or subdirectories as alternative to rules directories for straightforward use cases.

• Plain markdown without metadata
• Perfect for simple, readable instructions
• Supports nested AGENTS.md files in subdirectories

Running Agents in Parallel

Many agent harnesses support running multiple agents in parallel without them interfering with one another. Running multiple models on the same problem and picking the best result significantly improves the final output, especially for harder tasks.

Worktree Support

Some agent harnesses automatically create and manage git worktrees for parallel agents. Each agent runs in its own worktree with isolated files and changes, so agents can edit, build, and test code without stepping on each other.

To run agents in parallel: 1. Use the parallel execution features in your agent harness 2. When agents finish, review and merge the best changes

Run Multiple Models at Once

A powerful pattern is running the same prompt across multiple models simultaneously. Compare the results side by side and select the best solution.

This is especially useful for:

• Hard problems where different models might take different approaches
• Comparing code quality across model families
• Finding edge cases one model might miss

Best Practices

• Configure notifications and sounds so you know when agents finish
• Review all solutions before choosing
• Consider combining best parts from different solutions
• Use for complex problems where multiple approaches are valuable

When to Use Parallel Agents

• Complex refactorings
• Architectural decisions
• Difficult bugs
• Performance optimizations
• When you want to compare approaches

When to Use Single Agent

• Simple, straightforward tasks
• Quick fixes
• When you know the approach
• Time-sensitive work

Planning with Agents

Plan Mode

Many agent harnesses support Plan Mode (often activated with Shift+Tab or similar). Instead of immediately writing code, the agent will:

1. Research your codebase to find relevant files 2. Ask clarifying questions about your requirements 3. Create a detailed implementation plan with file paths and code references 4. Wait for your approval before building

Benefits

• Forces clear thinking about what you're building
• Gives agent concrete goals to work toward
• Creates reviewable documentation
• Makes it easy to resume interrupted work

Using Plans

• Plans open as Markdown files you can edit directly
• Remove unnecessary steps, adjust approach, add context
• Save plans to workspace (e.g., .cursor/plans/, .claude/plans/)
• Creates documentation for your team

When to Use Plan Mode

• Complex features requiring multiple files
• Architectural changes
• Large refactorings
• When you want to review approach before implementation

When to Skip

• Quick changes or fixes
• Tasks you've done many times before
• Simple, single-file changes

Starting Over from a Plan

If agent builds something that doesn't match what you wanted:

1. Revert the changes 2. Refine the plan to be more specific 3. Run it again

This is often faster than fixing an in-progress agent and produces cleaner results.

Reviewing Code

AI-generated code needs review, and agent harnesses provide multiple review options.

During Generation

Watch the agent work. The diff view shows changes as they happen. If you see agent heading in the wrong direction, press Escape to interrupt and redirect.

Agent Review

After agent finishes, use the review features available in your agent harness. Many provide dedicated review passes where the agent analyzes proposed edits line-by-line and flags potential problems.

For all local changes, compare against your main branch using available review tools.

Bugbot for Pull Requests

Push to source control to get automated reviews on pull requests. Many platforms provide automated analysis to catch issues early and suggest improvements.

Architecture Diagrams

For significant changes, ask agent to generate architecture diagrams. Try prompting: "Create a Mermaid diagram showing the data flow for our authentication system, including OAuth providers, session management, and token refresh."

These diagrams are useful for documentation and can reveal architectural issues before code review.

Review Best Practices

• Review carefully: AI-generated code can look right while being subtly wrong
• Read the diffs: Don't just trust that it works
• Test the changes: Run tests and verify functionality
• Check edge cases: Agent might miss edge cases
• Verify security: Check for security issues, especially with user input

The faster the agent works, the more important your review process becomes.

Common Workflows

Test-Driven Development

Agent can write code, run tests, and iterate automatically:

1. Ask agent to write tests based on expected input/output pairs. Be explicit that you're doing TDD so it avoids creating mock implementations for functionality that doesn't exist yet. 2. Tell agent to run the tests and confirm they fail. Explicitly say not to write implementation code at this stage. 3. Commit the tests when you're satisfied with them. 4. Ask agent to write code that passes the tests, instructing it not to modify the tests. Tell it to keep iterating until all tests pass. 5. Commit the implementation once you're satisfied with the changes.

Agents perform best when they have a clear target to iterate against. Tests allow agent to make changes, evaluate results, and incrementally improve until it succeeds.

Codebase Understanding

When onboarding to a new codebase, use agent for learning and exploration. Ask the same questions you would ask a teammate:

• "How does logging work in this project?"
• "How do I add a new API endpoint?"
• "What edge cases does CustomerOnboardingFlow handle?"
• "Why are we calling setUser() instead of createUser() on line 1738?"

Agent uses both grep and semantic search to look through codebase and find answers. This is one of the fastest ways to ramp up on unfamiliar code.

Git Workflows

Agents can search git history, resolve merge conflicts, and automate your git workflow.

Creating Commands

Commands are ideal for workflows you run many times per day. Store them as Markdown files in the appropriate commands directory (e.g., .cursor/commands/, .claude/commands/) and check them into git so your whole team can use them.

Example: Create PR Command

Create a pull request for the current changes.

1. Look at the staged and unstaged changes with `git diff`
2. Write a clear commit message based on what changed
3. Commit and push to the current branch
4. Use `gh pr create` to open a pull request with title/description
5. Return the PR URL when done

Other Command Examples

• /fix-issue [number]: Fetch issue details with gh issue view, find relevant code, implement a fix, and open a PR
• /review: Run linters, check for common issues, and summarize what might need attention
• /update-deps: Check for outdated dependencies and update them one by one, running tests after each

Agent can use these commands autonomously, so you can delegate multi-step workflows with a single / invocation.