title: "Context Management & Prompting" description: "How to give Cursor the right context and write prompts that produce accurate, first-try results." section: "Full Guide" readTime: "10 min"

Context Management & Prompting

The most common Cursor failure is not model capability — it's missing or noisy context. Give the agent what it needs, and nothing it doesn't, and first-try accuracy goes up.

Why Context Matters

Rule: a little more context costs a few tokens but usually saves 2–3 iterations. Cursor's agent also searches your codebase itself, so you point it at what it can't easily find.

The @ Mention Toolkit

Type @ in the Agent input to attach context.

You can also reference rules and skills: @rulename applies a manual rule, and /skill-name invokes a skill. For library docs, add an MCP server such as Context7 to .cursor/mcp.json:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

Then ask the agent to use Context7 for the library and version you care about. Cursor asks for approval before using MCP tools by default.

The 3-File Pattern

A reliable starting point for a prompt is three references:

1. @the-file-to-edit.ts        — what you're changing
2. @similar-existing-feature.ts — the pattern to follow
3. @types-or-utilities.ts      — shared types and helpers

Example — adding a new API endpoint:

Add POST /api/products endpoint.

@src/routes/orders.ts    (follow this route's pattern)
@src/models/Order.ts     (use this model pattern)
@src/types/api.ts        (use existing response types)

Requirements:
- Validate input with Zod (see orders.ts)
- Return standard ApiResponse<Product> (see types)
- Handle 400/404/500 consistently

Why it works: The pattern file eliminates style guessing. Types prevent hallucinated interfaces. Three files keeps context focused. Treat it as a guideline, not a hard rule.

Context Budget by Task Size

More context isn't always better — it can distract the agent. Match your context to task complexity:

When trimming, prioritize: types > tests > implementations.

AGENTS.md and Rules — Your Project's Permanent Context

Standing context belongs in AGENTS.md or an Always Apply rule in .cursor/rules/, not in every prompt. Cursor includes them for you, so you don't need to @-mention them. See Setup for the rule types.

# Project: [Name]
 
## Stack
- Next.js 14, React Server Components
- Prisma ORM, PostgreSQL
- Tailwind CSS, shadcn/ui
- React Query v5 (NOT SWR)
 
## Conventions
- Server actions in `src/actions/*.ts`
- Components: PascalCase, one component per file
- Error handling: use Result<T> type (src/types/result.ts)
 
## Absolute rules
- No `any` types
- No console.log in prod code (use src/lib/logger.ts)
- All API inputs validated with Zod before processing
 
## Test requirements
- Unit tests for all utility functions
- Playwright E2E for critical user paths

Cursor recommends keeping each rule under 500 lines and referencing files rather than copying their contents.

Conversation Hygiene

Start a new chat for each task. Long sessions accumulate misunderstandings and noise. Use Cmd/Ctrl+L or Cmd/Ctrl+N for a new chat, and @Chats to bring forward context from an earlier one.

Use git commits and checkpoints as reset points. The agent takes checkpoints before significant changes (restoring reverts files, not chat history), but checkpoints are local and separate from git, so commit working states too:

git add -A && git commit -m "feat: add product search (checkpoint)"

Use side chats for tangents. /side (or /btw) opens a separate conversation so a quick question doesn't pollute the main thread.

Continuing a paused task:

Continuing [specific task].

Already done:
- Created ProductCard component
- Added API endpoint

Not yet done:
- Pagination
- Loading states
- Empty state

@src/components/ProductCard.tsx @src/api/products.ts

Debugging: switch to Debug Mode from the mode picker for hard bugs. For simple ones, a precise prompt works:

Bug: [exact behavior]
Expected: [what should happen]
Actual: [what's happening]

Error: [paste full error + stack trace]

@src/file-with-bug.ts @tests/file-with-bug.test.ts

Minimal fix only. Do not change architecture.

Anti-Patterns to Avoid

Context dumping — attaching everything "just in case":

# Bad
@src/ @tests/ @config/ @docs/
Fix the button style

# Good
@src/components/Button.tsx
Fix button style: border-radius should be 8px (currently 4px)

Zero context:

# Bad
Add user authentication

# Good
Add JWT authentication to the Express API.
@src/middleware/ @src/types/auth.ts
Use existing middleware pattern. Endpoints to protect: POST /api/orders, DELETE /api/products/:id

Mixed tasks — 4 unrelated requests in one prompt:

# Bad
Fix the button bug AND add a new endpoint AND refactor the auth module AND update tests

# Good — split into separate focused chats, each with their own context
Chat 1: Fix button bug — @Button.tsx
Chat 2: Add endpoint — @routes/orders.ts @types/api.ts

Assuming context carries over:

# Bad (in a new chat)
"Continue from where we left off"

# Good
"Continue adding caching to the search endpoint.
Last state: endpoint works, no caching yet.
@src/api/search.ts @src/lib/redis.ts"