Context Patterns

You ask Agent to add error handling to your Express route. It wraps everything in a try-catch and returns { error: "Something went wrong" }. Meanwhile, your codebase has a custom AppError class, a centralized error handler middleware, and a standard error response format with error codes. The agent did not know about any of this because you did not tell it, and it did not find it on its own.

The quality of Cursor’s output is directly proportional to the quality of context you provide. Too little context and the agent guesses. Too much context and it loses focus on the important parts. The sweet spot is precise, relevant context that tells the agent exactly what patterns to follow.

What You’ll Walk Away With

• A decision framework for when to use each type of @ mention
• Strategies for building context efficiently without over-loading the prompt
• Patterns for using rules to provide background context automatically
• Techniques for debugging context issues when the agent produces poor output

The @-Mention System

Cursor’s @ mentions are your primary tool for providing context. Type @ in the chat input and select from:

Mention Type	What It Does	Token Cost	Best For
@file	Includes the full content of a specific file	Medium-High	Showing exact patterns to follow
@folder	Provides a structural overview of a directory	Low-Medium	Giving the agent a map of your project
@code	Includes a specific function or class	Low	Pinpointing exactly what to reference
@docs	Searches indexed documentation	Medium	Library/framework-specific guidance
@past-chats	References a previous conversation	Medium	Building on earlier work

File Mentions: Show, Don’t Tell

Instead of describing your patterns in words, show the agent the actual code:

# Bad: Describing the pattern (agent may not follow it)
"Create an API endpoint. We use Express with middleware for auth,
Zod for validation, and return JSON with status codes."

# Good: Showing the pattern (agent replicates it)
"Create a POST /api/orders endpoint following the exact pattern
in @src/routes/users.ts -- same middleware, validation, error
handling, and response format."

Tip

Copy-paste prompt for pattern-based implementation:

Create [NEW THING] following the exact patterns in @[EXISTING EXAMPLE].

Same structure, same error handling, same response format.
Only change the domain-specific logic.

Replace [NEW THING] and [EXISTING EXAMPLE] with your specifics. This two-line prompt consistently produces higher-quality output than a 20-line description of what you want.

Folder Mentions: When You Need a Map

Use @folder when the agent needs to understand the structure of a directory but does not need to read every file:

Look at @src/components/ and create a new NotificationBanner
component that follows the same file organization and naming
conventions as the existing components.

Folder mentions are much cheaper in tokens than attaching every file. The agent gets a list of files and can choose which ones to read in detail.

Code Mentions: Surgical Precision

When you need the agent to reference a specific function or class without including the entire file:

Refactor the calculateDiscount function in @Code:src/services/pricing.ts:calculateDiscount
to support percentage-based and fixed-amount discounts.

This is the most token-efficient way to provide context for targeted edits.

Context Strategies

Strategy 1: Minimum Viable Context

Start with the least context possible and add more only if the output is wrong:

1. Give the agent just the task description
2. If it produces incorrect patterns, add the canonical example file
3. If it still misses conventions, add the relevant rule
4. If it creates wrong file structure, add a folder mention

This approach minimizes token usage while ensuring the agent gets what it needs.

Strategy 2: Pattern-Reference Context

For tasks that should follow existing patterns, always include one canonical example:

Create src/services/notification-service.ts.

Pattern reference: @src/services/email-service.ts
- Same class structure
- Same error handling approach
- Same dependency injection pattern
- Same test file organization

One good example file is worth more than a page of written instructions.

Strategy 3: Boundary Context

When the agent needs to know what NOT to touch:

Add rate limiting to the /api/users routes in @src/routes/users.ts.

Context:
- @src/middleware/auth.ts (existing middleware pattern to follow)
- @src/routes/users.ts (the file to modify)

Boundaries:
- Do NOT modify any other route files
- Do NOT change the middleware loading order in app.ts
- Do NOT install new packages -- use the built-in Node.js APIs

Strategy 4: Documentation Context

Use @docs to give the agent framework-specific knowledge:

@docs Next.js Add server-side data validation using Next.js 14
Server Actions. Follow the official patterns for form handling
and error states.

Add custom documentation sources in Cursor Settings > Indexing & Docs. If you use an internal framework or proprietary library, add its documentation URL so agents can reference it.

Tip

Copy-paste prompt for adding project documentation:

Add the following documentation sources to Cursor for this project:
1. Our API documentation: [your-docs-url]
2. Our design system: [your-design-system-url]
3. Our internal SDK: [your-sdk-docs-url]

Go to Cursor Settings > Indexing & Docs > Add New Doc and paste each URL.

Diagnosing Context Issues

When the agent produces poor output, the cause is almost always one of these context problems:

Agent uses the wrong patterns. It did not see your canonical example. Add a @file reference to the file it should be imitating.

Agent creates files in the wrong location. It does not know your project structure. Add a @folder reference to show where things go.

Agent uses outdated APIs or deprecated patterns. It is relying on training data instead of your codebase. Add @docs for the current version of the framework.

Agent includes unnecessary complexity. Your prompt is too vague. Add explicit boundaries: “Do NOT add caching. Do NOT add logging. Just the core logic.”

When This Breaks

Too much context confuses the agent. If you attach 10+ files, the agent may focus on irrelevant ones. Reduce to the 2-3 most important files and let the agent explore if it needs more.

@docs returns outdated information. Cursor’s documentation index may be stale. Re-index the documentation source in Cursor Settings or add the URL again.

Agent cannot find files with @file mentions. Check that the file path is correct. Use the autocomplete dropdown after typing @ to browse available files.

Rules and file context conflict. If a rule says “use camelCase” but the referenced file uses snake_case, the agent gets confused. Ensure your rules and examples are consistent.

What’s Next

• Prompt Templates — Templates that build on these context strategies
• Snippet Management — Code snippets as reusable context
• Token Management — The cost side of context management