Cursor

Cursor is a VS Code fork built around AI agents that can read your repo, edit multiple files, and run terminal commands.

Modes: When to Use What

Rule of thumb: Plan → approve → Agent → verify with tests. Skipping Plan on large tasks leads to over-refactoring.

Session Walkthrough: Fix a Failing Test

Here is a typical Plan → Agent cycle. The same pattern applies to any scoped task.

1. Open Plan mode. Paste the error with context:

Plan mode — do not implement yet.

Test failing in CI: npm test -- src/utils/formatDate.test.ts

Error:
  Expected: "Jan 1, 2026"
  Received: "1/1/2026"

@src/utils/formatDate.ts
@src/utils/formatDate.test.ts

Propose a fix. List every file you would change. Do not touch anything outside src/utils/formatDate*.

2. Review the plan. Reject anything that touches unexpected files. Cursor will list proposed changes — decline if the plan mentions unrelated modules.

3. Switch to Agent mode with the approved plan:

Implement the approved plan. Only edit src/utils/formatDate.ts.
Run npm test -- formatDate when done.

4. After Agent finishes, review the diff — Cursor highlights every changed line. Reject hunks that rewrite logic you did not ask for.

5. Run your test suite locally before accepting. If tests still fail, paste the new error:

Tests still fail:
  AssertionError: expected "Jan 1" received "January 1"

Fix formatDate.ts only. Do not change the test.

This pattern — Plan to bound scope, Agent to implement, human to verify — is the core loop. See Agentic Workflows for failure recovery.

@-Mentions (Context)

Attach context explicitly instead of hoping the model finds it:

Prefer @Files over pasting large blobs. Cursor indexes your repo and respects .cursorignore.

Too much context hurts. Attaching the whole src/ directory dilutes focus. Attach the 2–3 files directly relevant to the task.

Project Rules

Store persistent instructions in .cursor/rules/ so every session starts with your conventions.

<!-- .cursor/rules/stack.mdc -->
---
description: Stack versions and coding conventions for this project
alwaysApply: true
---

# Stack
- Next.js 15 App Router
- React 19
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with Postgres

# Conventions
- Use server components by default; add "use client" only when needed
- Zod for all external input validation
- Named exports only (no default exports except page.tsx / layout.tsx)
- Test files colocated: src/lib/foo.test.ts alongside src/lib/foo.ts

# Boundaries
- Do not modify package-lock.json, .github/**, or drizzle/migrations/**
- Test command: npm test
- Lint command: npm run lint

Rules are injected into every request — keep them under ~500 tokens. Rules that apply to specific files can use globs:

<!-- .cursor/rules/api-routes.mdc -->
---
description: Rules for Next.js API route handlers
globs: ["app/api/**/*.ts"]
---

- Always validate request body with Zod before processing
- Return typed Response.json() — never untyped objects
- Check auth with `await auth()` at the top of every handler
- Set maxDuration for long-running routes

See Project Rules for team rollout and AGENTS.md templates.

.cursorignore

Tell Cursor what not to index. Large or sensitive directories waste context and risk leaking secrets.

# .cursorignore

# Build output
.next/
out/
dist/

# Dependencies
node_modules/

# Environment and secrets
.env
.env.local
.env*.local
*.pem
*.key

# Large generated files
*.lock
public/fonts/
public/videos/

# Database migrations (prevent accidental edits)
drizzle/migrations/

# Test snapshots (noisy context)
**/__snapshots__/

.cursorignore uses the same syntax as .gitignore. If the AI is referencing outdated build output or suggesting changes to migrations, your ignore file is probably missing those paths.

Composer and Multi-File Edits

Composer (Cmd+I / Ctrl+I) is for scoped edits across files. Give it:

1. Goal: one sentence
2. Constraints: files, patterns, things to avoid
3. Verification: "run tests after changes"

Reject diffs that touch unrelated files. If Composer touches more than 5 files on a task you expected to be 2 files, cancel and break the task into smaller prompts.

Background Agents

Background agents run tasks while you continue working. Good for:

• Test suite runs across a branch
• Documentation passes
• Repetitive refactors with clear rules

Bad for: ambiguous features, security-sensitive code, or anything needing your design input mid-flight.

Set explicit file boundaries and a required verification command (npm test) before starting a background agent. Without boundaries, it will wander.

MCP Integration

Connect external tools via Model Context Protocol servers: databases, APIs, issue trackers. Configure in Cursor Settings → MCP.

Common Cursor Mistakes

• Too much context: attaching the whole repo dilutes focus; attach relevant files only
• No verification step: always run lint/test after Agent sessions
• Skipping Plan: large tasks need explicit scope approval first
• Ignoring .cursorignore: exclude node_modules, build output, and secrets from indexing
• Accepting full diffs without reading: review every changed file; agents touch unexpected things

Related

• OpenAI Codex
• Devin Desktop
• Cursor Shortcuts Cheat Sheet
• Prompting for Code
• Agentic Workflows
• Choosing a Tool