Chapter 3: Your Primary Tool - Cursor

Cursor is the AI-powered code editor at the forefront of AI-assisted development. Unlike simpler autocomplete tools, Cursor can ingest your entire project context and generate or modify multiple files at once.

This chapter gets you productive with Cursor fast.

Setting Up Cursor for Success

//Install Cursor

Download from cursor.com. It's built on VS Code, so if you use VS Code, you'll feel right at home.

//Understand the Interface

Cursor combines what used to be separate features (Chat, Composer, Agent) into one unified interface:

Chat pane - Your main interface for AI assistance
Agent mode - AI that can read files, run commands, and iterate
Ask mode - Simple Q&A without taking actions

Always use Agent mode for writing code. It can explore your codebase and make changes across files.

Custom Rules: Your Secret Weapon

Cursor Rules are configuration files that define how the AI should respond. They're like custom instructions that apply to every conversation.

//Global Rules

Global rules apply to ALL your Cursor sessions. Set them in: Settings → Cursor Settings → Rules

Recommended global rules to start with:

- Be concise. Give the answer immediately without restating my question.
- Treat me as an expert programmer unless I'm asking for explanation.
- Be accurate and thorough.
- If making an educated guess, say so.
- If you need more context, ask. Don't assume.
- For code changes, show just the changed lines with a few lines of context.

//Project Rules

Project rules apply to a specific codebase. Store them in .cursor/rules/ in your project root.

Example .cursor/rules/react.mdc:

# React Project Rules

- Use functional components with hooks, not class components
- Use TypeScript for all new files
- Follow existing naming conventions in the codebase
- When creating components, include PropTypes or TypeScript interfaces
- Prefer named exports over default exports

//Why Rules Matter

Rules are persistent context. Instead of repeating "use TypeScript" in every prompt, put it in a rule once. The AI sees it automatically.

Good rules to include:

Your tech stack and versions
Coding style preferences
Patterns to follow or avoid
Testing conventions

Agent Mode and YOLO Mode

//Agent Mode

In Agent mode, Cursor can:

Read and search files in your project
Make changes across multiple files
Run terminal commands
Iterate until the task is complete

Always use Agent mode for real work. It's what makes Cursor powerful.

//YOLO Mode (Auto-Run)

YOLO mode lets Cursor run terminal commands without confirmation.

To enable: Settings → Features → Auto-run mode

Before enabling YOLO mode, set up safety guardrails:

Use version control. Commit before letting Cursor make big changes.
Set up a command allowlist. Only let Cursor auto-run safe commands:

npm test npm run lint npm run build pytest rails test
Or use a denylist. Block dangerous commands:

rm mv kill sudo DROP DELETE
Never use production environment variables. Keep production credentials out of your local environment.

//When to Use YOLO Mode

Good for:

Running tests repeatedly while iterating
Lint/format commands
Build commands

Avoid for:

Commands that modify files outside your project
Database operations
Deployment commands

@ References: Controlling Context

The @ symbol lets you explicitly include context in your prompts.

//Reference Types

Reference	What It Does	When to Use
`@file path/to/file.js`	Include a specific file	When discussing specific code
`@folder src/components`	Include a folder	When working across related files
`@codebase`	Search entire project	When you're not sure where something is
`@docs`	Include documentation	For library/framework questions
`@web`	Search the web	For recent information or updates
`@git`	Include git history	For understanding recent changes

//Best Practices

Be specific. @file src/auth/login.ts beats hoping Cursor finds the right file.

Combine references. You can use multiple:

@file src/types/user.ts @file src/api/users.ts

How do I update the User type to include a profilePicture field
and update the API to handle it?

Don't over-reference. Including everything dilutes the context. Include what's relevant.

Effective Cursor Workflows

//For Bug Fixes

Start a new chat
Include the relevant file: @file path/to/broken/code.ts
Paste the error message
Ask for the fix

@file src/api/payments.ts

Getting this error when processing payments:

TypeError: Cannot read property 'amount' of undefined
at processPayment (payments.ts:47)

What's causing this and how do I fix it?

//For New Features

Start a new chat
Reference related existing code
Describe what you want clearly
Let the agent iterate

@folder src/components/forms

Create a new ContactForm component that:
- Has fields for name, email, and message
- Validates email format
- Uses the same styling as other forms in this folder
- Submits to /api/contact

//For Refactoring

Reference the code to refactor
Explain the goal
Ask for a plan first if it's big

@file src/utils/helpers.ts

This file has grown too large. Suggest how to split it into
smaller, focused modules. Then implement the refactoring.

Advanced: Parallel Agents

Cursor can run multiple AI agents in parallel, each trying different approaches. This is useful when you're not sure of the best solution.

To use: Enable "Best of N" in settings and set the number of parallel attempts.

When it helps:

Complex problems with multiple valid solutions
When you want to compare approaches
When initial attempts are failing

Cost consideration: Parallel agents use more API credits, so use judiciously.

Common Mistakes to Avoid

Using one long chat for everything. Start fresh for new tasks.
Not including enough context. Use @ references to be explicit.
Including too much context. Don't dump your whole codebase. Include what's relevant.
Accepting code without understanding. Review changes, especially for anything important.
Not setting up rules. A few minutes of setup saves hours of repeated instructions.
Fighting the agent. If it's going the wrong direction, start fresh with clearer instructions.

Key Takeaways

Use Agent mode for real work. It's what makes Cursor powerful.
Set up rules immediately. Global rules for preferences, project rules for tech stack.
Master @ references. Explicit context beats hoping Cursor guesses right.
Start fresh for each task. New chat = clean context.
Use YOLO mode carefully. Set up allowlists/denylists and always use version control.
Review what you accept. AI makes mistakes. Stay in the loop.

Next: When to use Claude Code and ChatGPT instead of Cursor.