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: "12 min"

Context Management & Prompting

The most common Cursor failure is not model capability — it's missing context. Give the agent what it needs and accuracy jumps from ~60% to ~90%.

Why Context Matters

Scenario	Hallucination Rate	First-try Success	Notes
No context	40–60%	~30%	Agent guesses patterns
File only	20–30%	~60%	Missing project conventions
File + rules + examples	5–15%	~88%	Best real-world results

Rule: more context costs a few extra tokens but saves 2–3 iterations.

The @ Mention Toolkit

Syntax	When to Use	Scope
`@filename.ts`	Small, focused file (<200 lines)	One file
`@src/components/`	Medium folder, find patterns	Folder tree
`@codebase`	Broad search across repo	Full index
`@instructions.md`	Always include for your project	Project config
`@web "react query v5 docs"`	API changes, live info	Current web
`#Context7`	Auto-fetches version-specific library docs	MCP server
`@https://docs.example.com`	Static external docs	URL crawl

Install Context7 MCP for library-aware code:

# Add to .cursor/mcp.json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

Cursor will automatically pull version-matched docs when you mention libraries.

The 3-File Rule

Every prompt should reference exactly three files:

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.

Context Budget by Task Size

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

Task Type	Target Context	What to Include
Quick edit	~2k tokens	1–2 files
New feature	~5k tokens	3-file rule + instructions.md
Refactor	~10k tokens	Component tree + tests + types
Architecture	~50k tokens	Full module + ADRs + examples

When staying under budget, prioritize: types > tests > implementations.

`instructions.md` — Your Project's Permanent Context

This file is included in every Composer session. Keep it tight.

# 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
- API routes: never expose internal IDs, always map to slugs
- Error handling: use Result&lt;T&gt; type (src/types/result.ts)
 
## Absolute rules
- No `any` types
- No inline styles
- 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
- Integration tests for API endpoints
- Playwright E2E for critical user paths

Keep it under 200 lines. Run @instructions.md at the start of every Composer session.

Conversation Hygiene

Reset every 20 exchanges. Context drift is real — the agent accumulates misunderstandings over long sessions.

Use git commits as reset points:

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

Then start fresh Composer session:

Starting fresh on [task].
Context:
- We just merged the product search feature
- Next: pagination for search results

Relevant: @src/features/search/ @src/types/pagination.ts @instructions.md

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 @instructions.md

Debug mode:

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 @instructions.md

Do NOT change architecture. Minimal fix only.
Debug approach: binary search — check if issue exists in simplest form first.

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 @instructions.md
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 sessions, each with their own context
Session 1: Fix button bug — @Button.tsx
Session 2: Add endpoint — @routes/orders.ts @types/api.ts @instructions.md

Assuming context carries over:

# Bad (after resetting conversation)
"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 @instructions.md"

Context Management & Prompting

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: "12 min"

Context Management & Prompting

Why Context Matters

The @ Mention Toolkit

The 3-File Rule

Context Budget by Task Size

instructions.md — Your Project's Permanent Context

Conversation Hygiene

Anti-Patterns to Avoid

`instructions.md` — Your Project's Permanent Context