✓ Updated July 5, 2026
Sources: Cursor official docs · .cursorrules community · Cursor 2.6 changelog
How to Prompt Cursor: Complete Guide from Beginner to Expert (2026)
Cursor is not a chatbot you happen to code with. It is an AI coding environment where prompting works differently from everything else. The context comes from your codebase, not just your words. The model sees your files, your cursor position, your error messages. Knowing how to give Cursor the right context — and how to write the right instructions in .cursorrules — is the difference between AI that helps and AI that makes a mess.
The Core Principle
Cursor rewards prompts that leverage its context primitives — @file, @docs, @codebase — and project instructions in .cursorrules. The more precisely you point Cursor at the right context, the better the output. Prompting Cursor well is less about phrasing and more about pointing: point at the right files, the right docs, the right scope. Then give a clear, outcome-focused instruction.
AI Prompting Guides — Full Series
🟣
Claude
XML tags, system prompts, 30% placement rule
🟢
ChatGPT
Output contracts, reasoning effort, few-shot
🔵
Gemini
Search grounding, 1M context, multimodal
🎨
Midjourney
Parameters, weighting, style references
⌨️
Cursor
.cursorrules, @mentions, agent mode scope
⚡
Grok
Live X data, DeepSearch, Imagine prompts
Basic: Chat, Composer, and How Cursor Reads Context
Basic level
The three ways to interact with Cursor
| Mode | What it does | When to use |
|---|
| Inline edit (Cmd+K) |
Edits the selected code or generates code at your cursor position |
Small, targeted changes — fix this function, add a parameter, rename a variable |
| Chat (Cmd+L) |
Conversational AI with awareness of your open file and codebase |
Questions, explanations, planning — "why is this function slow?" "how should I structure this?" |
| Composer / Agent (Cmd+I) |
Multi-file, multi-step autonomous coding — reads, creates, edits files across the project |
Large features, refactors, building new modules — tasks that span multiple files |
The most common beginner mistake: using Chat to ask Cursor to write code that should be in Composer. Chat explains and suggests. Composer implements. If you want actual code written and applied, use Composer.
What context Cursor automatically has
By default, Cursor can see:
- The file you currently have open
- The code you have selected or highlighted
- The cursor position and surrounding code
- Your .cursorrules file (if it exists)
- Recent errors in the terminal (if you have enabled terminal context)
Cursor does not automatically read your entire codebase. For large projects, it uses semantic search to find relevant files — but this search is imprecise. The @mentions system (covered next) is how you point Cursor at exactly what it needs.
Basic prompt structure for Cursor
✗ Weak — vague, no context, no scope
Fix the bug in my login function.
✓ Strong — specific, scoped, outcome-defined
@auth/login.ts @auth/middleware.ts
The login function throws a JWT verification error when the token contains special characters in the username field.
Error message: "JsonWebTokenError: invalid signature"
This only happens with usernames containing underscores or hyphens.
Fix the JWT signing in login.ts to handle special characters correctly.
Do not change the middleware — only fix the source of the malformed token.
Add a unit test that verifies special character usernames sign and verify correctly.
Intermediate: @Mentions, Context Management, Inline Editing
Intermediate level
The @mention system — how to give Cursor the right context
The @ symbol in Cursor is how you explicitly point the AI at specific resources. This is the most important prompting skill for Cursor — vague context produces vague code.
| Mention | What it does | Example use |
|---|
@filename | Includes a specific file in context | @api/routes.ts — when editing code that depends on the routes file |
@folder | Includes all files in a folder | @components/ — when building a component that needs to match existing patterns |
@codebase | Semantic search across entire codebase | Use when you don't know which file has the relevant code |
@docs | Fetches and includes documentation from a URL | @docs [URL] — when you need Cursor to follow a specific library's API |
@web | Searches the web for current information | @web "React 19 concurrent features" — for up-to-date library behavior |
@git | Includes recent git diff or commit history | @git — when debugging a regression introduced in recent commits |
@terminal | Includes terminal output (errors, logs) | Paste the failing test output, then use @terminal to give Cursor the context |
Context budget: More context is not always better. Cursor has a context window limit. Providing 20 files when 3 are relevant degrades output quality — the model has to search through noise to find signal. Be selective. Mention only the files that are directly relevant to the task.
Inline editing — Cmd+K for targeted changes
Select the exact code you want to change, press Cmd+K, and type your instruction. The instruction should describe the outcome, not the method:
✗ Process-focused (weak)
Loop through the array and check each item against the condition and add matching items to a new array and return it.
✓ Outcome-focused (strong)
Return only items where status === 'active' and createdAt is within the last 30 days.
For inline edits: be specific about what to change and what to leave alone. "Add error handling" is weak. "Add a try/catch that catches network errors specifically, logs them to console.error with the request URL, and returns null instead of throwing" is strong.
Advanced: .cursorrules — The Project System Prompt
Advanced level
What .cursorrules is
The .cursorrules file lives in your project root and is automatically included in every Cursor session as a persistent system prompt. It is the single most powerful thing you can do to improve Cursor's output quality across an entire project. Every developer who opens the project gets the same AI behavior — consistent with the project's conventions, stack, and standards.
Think of it as CLAUDE.md for Cursor — a file that tells the AI everything it needs to know about your project before it touches any code.
What to put in .cursorrules
Example .cursorrules for a Next.js TypeScript project
# Project: [Your Project Name]
## Stack
- Next.js 15 (App Router), TypeScript 5.3, Tailwind CSS, Prisma, PostgreSQL
- Package manager: pnpm (not npm or yarn)
- Testing: Vitest + Testing Library
## Code conventions
- All components: functional, named exports only (no default exports except pages)
- File naming: kebab-case for files, PascalCase for components
- Types: define in /types directory, import with @/types/
- Never use 'any' type — use 'unknown' and narrow it
- Async functions: always handle errors explicitly — no unhandled promise rejections
## What to NEVER do
- NEVER commit directly — always create a branch
- NEVER delete or modify .env files
- NEVER install new packages without checking with the user first
- NEVER change the database schema directly — write a migration
## How to handle ambiguity
- If a task requires modifying files outside the stated scope, stop and ask
- If you find a security vulnerability while working on an unrelated task, report it immediately before continuing
## Testing requirements
- Every new function must have at least one unit test
- Every new API route must have an integration test
- Run tests after every change: pnpm test
## When asked to "fix a bug"
1. Read the failing test or error message first
2. Identify the root cause (not just the symptom)
3. Fix the root cause
4. Verify the fix does not break other tests
5. Report what you changed and why
Advanced .cursorrules patterns
Beyond basics, effective .cursorrules files include:
- Architecture decisions — "State management uses Zustand, not Redux. Never introduce Redux."
- Banned patterns — "Never use useEffect for data fetching — use React Query's useQuery hook."
- File structure rules — "New API routes go in /app/api/[route]/route.ts — match existing patterns."
- Security rules — "All user input must be validated with Zod before use. Never trust raw request body."
- Performance rules — "Images must use Next.js Image component. Never use raw img tags."
With Cursor 2.6 agentic mode: .cursorrules need to include explicit safety boundaries. The model will now autonomously create files, run terminal commands, and modify multiple files — without asking. If you do not specify what it should NOT do, it will do things you did not intend. Always include a "What to NEVER do" section.
Expert: Agent Mode, Agentic Workflows, Safety Rules
Agent mode — what it changes
Cursor's Agent mode (Composer with agentic behavior enabled) turns Cursor into an autonomous worker. It reads files, creates new ones, runs terminal commands, installs packages, and iterates on failures — without asking permission for each step. This is enormously powerful and requires careful prompting to avoid unintended consequences.
Agent mode prompt structure for large tasks:
Task: Build a user authentication system with email/password login.
Scope:
- Files to create: /app/api/auth/, /components/auth/, /lib/auth.ts
- Files to modify: /app/layout.tsx (add AuthProvider), /middleware.ts (add route protection)
- Do NOT modify: database schema (migrations must be reviewed manually), /components/ui/ (shared components)
Requirements:
1. Use NextAuth.js v5 — check @docs for v5 API (not v4 which you may have trained on)
2. Store sessions in the database (not JWT) using Prisma adapter
3. Protected routes: /dashboard/*, /profile/*
4. Public routes: /, /login, /signup, /api/auth/*
Constraints:
- Run pnpm test after each major step. Stop if tests fail and report the failure before continuing.
- Do not install any packages not already in package.json without asking first.
- If you encounter an ambiguity in the NextAuth v5 API, check @web before making an assumption.
When complete: report every file you created or modified, with a one-sentence description of what each change does.
Dependency verification — critical for agent mode
In agent mode, Cursor may import packages that it assumes exist. Always add to your .cursorrules and large-task prompts:
Before importing any package, verify it exists in package.json. Run: cat package.json | grep [package-name]
NEVER assume a package is installed based on training data. If it is not in package.json, ask before installing.
Before/After Rewrites — Real Examples
Example 1 — Debugging
✗ Weak
My tests are failing. Fix them.
✓ Strong
@tests/auth.test.ts @lib/auth.ts @terminal
The test "should reject expired JWT tokens" is failing with:
Error: Expected 401, received 200
The test was passing yesterday before I updated the JWT expiry logic in lib/auth.ts.
1. Read the failing test to understand what it expects
2. Trace through the auth.ts code to find why expired tokens are returning 200 instead of 401
3. Fix only the expiry check — do not change any other auth behavior
4. Verify the fix by running: pnpm test auth.test.ts
5. Report exactly what you changed
Example 2 — Feature building
✗ Weak
Add a search feature to the app.
✓ Strong
@components/ui/ @app/dashboard/ @prisma/schema.prisma @lib/db.ts
Add a search bar to the dashboard that searches the 'products' table.
Requirements:
- Search by: product name (fuzzy match) and SKU (exact match)
- Results: show as a dropdown below the search bar, max 8 results
- Each result: product name, SKU, and current stock count
- Debounce: 300ms after user stops typing before firing the query
- Empty state: "No products found" message
- Loading state: show skeleton while fetching
Implementation:
- API route: /app/api/products/search/route.ts (GET with ?q= query param)
- Component: /components/dashboard/ProductSearch.tsx
- Database: use existing Prisma client from lib/db.ts — do not create a new connection
Match the existing component patterns in /components/ui/ — use the same Button and Input components already there.
Run pnpm test after building. Report every file created or modified.
5 Failure Modes and Fixes
Failure mode 01
Cursor uses the wrong version of a library
Root cause: Cursor's training data includes older library versions. Without being told to check current docs, it will use the API it knows from training — which may be v4 when you are running v5, or use deprecated methods.
Fix: Always specify the library version and add @docs with a URL to the current documentation. "Use NextAuth.js v5 — check @docs https://authjs.dev for the v5 API. Do not use v4 patterns." This forces Cursor to retrieve current docs before generating code.
Failure mode 02
Agent mode modifies files you did not intend to change
Root cause: Without explicit scope boundaries, agent mode will make changes wherever it determines they are necessary. This is technically correct behavior — but the agent's judgment of "necessary" may not match yours.
Fix: Always specify "Files to modify" and "Do NOT modify" sections in agent mode prompts. Also add to .cursorrules: "Do not modify files outside the stated scope without asking. If you believe changes are needed elsewhere, stop and report what you found before continuing."
Failure mode 03
Cursor generates code that works but violates your conventions
Root cause: Without .cursorrules, Cursor defaults to its trained preferences — which may use different state management patterns, naming conventions, or import styles than your project. The code works but is inconsistent with everything else.
Fix: Set up a .cursorrules file before starting any project. Include your stack, naming conventions, banned patterns, and file structure rules. The 30 minutes spent writing .cursorrules saves hours of reviewing and reverting code that works but doesn't fit.
Failure mode 04
Cursor installs packages without permission
Root cause: In agent mode, if Cursor decides a package is needed to complete a task, it will run the install command — adding dependencies to your project without your review. Some of these may have security issues, licensing problems, or be poor choices for your stack.
Fix: Add to .cursorrules: "NEVER install packages without explicit user permission. If a package is needed, stop and ask: 'I need to install [package]. Should I proceed?' Never run npm install, pnpm add, pip install, or equivalent commands autonomously."
Failure mode 05
Cursor writes broad catch blocks that hide errors
Root cause: Cursor's training includes a lot of code that uses broad try/catch patterns. Without explicit instructions, it will add catch (error) { console.log(error) } blocks that silently swallow errors — which makes debugging future issues much harder.
Fix: Add to .cursorrules: "Error handling rules: never use empty catch blocks. Never use catch blocks that only log and continue silently. Errors should be re-thrown after logging, or handled with a specific recovery path. No broad error suppression." Then enforce it in code review.
Cursor vs GitHub Copilot: Which is Better?
Full side-by-side comparison on autocomplete, agent mode, context handling, and pricing.
Cursor vs Copilot →