Cursor Chat Complete Guide — @ References, Context Control, and Prompt Templates

Chapter 5: Cursor Chat Complete Guide — @ References, Context Control, and Prompt Templates

Cursor Chat's power comes from the @ reference system. @filename pins the exact code the AI sees. @Codebase runs semantic search across your whole project. @Web fetches real-time information. @Git connects your questions to commit history. Without @ references, you're asking the AI to answer with a blindfold on. This chapter covers every @ type, explains why context quality determines answer quality, and provides 20 copy-paste prompt templates for the most common dev scenarios.

Pick the Right Tool First: Chat vs Cmd+K vs Composer

Using the wrong tool and blaming poor AI output is a common trap. The decision is mechanical once you know the rules.

The @ Reference System: Complete Guide

Type @ in the Chat input to open the reference menu. This is the fundamental difference between Cursor Chat and plain ChatGPT — you control exactly what information the AI sees.

@filename (most common)

Sends the complete content of a specific file to the AI. Far more precise than hoping the AI guesses the right file.

@src/auth/middleware.ts Why does this middleware return 401 for every request?
I've verified the token is valid, but every request gets intercepted.

@prisma/schema.prisma @src/repositories/UserRepository.ts
Are the User model fields consistent between these two files?
I suspect they've gotten out of sync.

You can @ multiple files simultaneously. When a question involves the relationship between files, you must include both — the AI cannot reason about cross-file interactions from one side only.

@Codebase (semantic search across the project)

Does not stuff the entire codebase into context. Instead performs vector semantic search and retrieves the most relevant code snippets. Use when you don't know which file contains the relevant code.

@Codebase Is there duplicate database connection initialization code?
I've seen new PrismaClient() in several places and want to centralize it.

@Codebase Where is the JWT token generated and where is it validated?
List all related files and approximate line numbers.

@Codebase vs @filename: When you know which file, use @filename (more precise, fewer wasted tokens). When you don't know, use @Codebase.

@Web (real-time internet search)

Lets the AI search for current information — essential for library versions, APIs, and best practices published after the model's training cutoff.

@Web How does React 19's use() hook combine with Suspense?
What are the known gotchas?

@Web What's different about Bun 1.x's HTTP server API vs Node.js?
I want to migrate an Express app to Bun.

Web search quality varies — verify important findings against official docs before using them.

@Docs (official documentation)

Cursor has built-in documentation indexes for React, Next.js, Tailwind CSS, and others. In Cursor Settings → Features → Docs you can add custom URLs — your internal API docs, third-party library docs — so the AI reasons from authoritative sources.

@Docs/Next.js How does generateMetadata handle dynamic route parameters in App Router?
Show a complete SEO configuration example for a blog post page.

@Docs/Prisma Under what conditions does Prisma's upsert fail?
How does its concurrency safety compare to a read-then-update pattern?

@Git (analyze commit history)

References Git commit history and diffs. Especially useful for "when was this bug introduced?" investigations.

@Git What changed in the last 5 commits? Could any of those changes cause login failures?

@Git When was this file last modified and what was the intent of the change?

@Git Summarize the last two weeks of commits into a CHANGELOG draft
written for a non-technical audience.

Context Control — The Factor That Determines Answer Quality

90% of poor AI answers come from insufficient or wrong context. The AI isn't failing — you gave it too little to work with.

Bad example:

This function has a bug, fix it

The AI doesn't know which function. It will guess or produce a generic template response — zero value.

Good example:

@src/payment/stripe.ts lines 45–67, the createPaymentIntent function.
When processing orders with amount = 0, it throws:
  StripeInvalidRequestError: amount must be at least 50 cents

Context: our platform allows free orders (100% coupon applied), where the amount is 0.
Fix requirements:
1. When amount is 0, skip the Stripe call and mark the order as paid directly
2. When amount > 0, use the normal Stripe flow unchanged
3. Do not change the function signature (many callers depend on it)

The structural formula for high-quality prompts

[@relevant files] + [current state / problem symptom] + [desired outcome] + [constraints]

20 Copy-Paste Templates for Common Scenarios

Understanding Code (1-5)

Debugging (6-10)

Refactoring (11-15)

Learning New Technology (16-20)

Multi-Turn Conversation Techniques

When to start a new Chat

• Task type changes: Switching from debugging to new feature development — start fresh. Old context pollutes the new direction.
• Conversation exceeds 20–30 turns: Early context has been truncated. The AI will start "forgetting" important constraints.
• AI is going in the wrong direction: Instead of spending turns correcting it, start a new Chat and restate the requirements clearly.
• Unrelated topics: Keep different modules in different Chats.

How to persist important information

• Write architectural decisions into .cursorrules — automatically injected every conversation
• Write important API design conventions into CLAUDE.md or docs/decisions.md, reference with @file
• Never rely on "the AI remembers what I said last time" — it doesn't. Every new Chat starts from zero.

Chapter Key Points

1. Pick the right tool first: Chat for understanding and multi-file questions, Cmd+K for precise changes to selected code, Composer for cross-file feature development. Don't blame AI for poor output from the wrong tool.
2. @ references determine answer quality: Know the file → @filename; don't know → @Codebase; need current info → @Web; need doc support → @Docs; investigating history → @Git.
3. More precise context = more useful answers: The formula is "relevant files + problem symptom + desired outcome + constraints." Missing any component degrades the answer.
4. Context pollution is real: After 20+ turns or topic switches, start a new Chat. Don't try to solve everything in one session.
5. Persist important information: Architectural conventions in .cursorrules, API decisions in docs. Don't rely on AI's non-existent cross-conversation memory.