Chat & Context System

Beyond Single-File Edits

🔄 In Lesson 3, you learned Tab completion and Cmd+K for fast, surgical edits. Those tools work great when you know exactly what to change and where. But coding isn’t always that straightforward.

Sometimes you need to ask: “How does the payment flow work in this project?” or “What would I need to change to add email notifications?” These questions span multiple files, require understanding architecture, and need more context than a single code selection can provide.

That’s what Chat and the context system are for.

Chat (Cmd+L): Conversations About Code

Press Cmd+L to open the AI Chat panel on the right side. This is where you have full conversations with Cursor about your codebase.

What makes Cursor’s chat different from just pasting code into ChatGPT:

• It can automatically pull relevant files into the conversation
• It can read your entire project structure
• It can reference specific functions, classes, and imports
• It stays aware of what you’re looking at in the editor

Good chat prompts look like:

• “Explain what this function does and why it’s using recursion”
• “What’s the data flow from the API endpoint to the database in this project?”
• “I’m getting a TypeError on line 47 — what’s causing it?”
• “How should I structure a new feature for user preferences?”

Quick tip: Select some code in the editor, then press Cmd+Shift+L to open chat with that code already embedded. Faster than copy-pasting.

The @ Symbol System

The @ symbol is how you give Cursor precise context. Without it, the AI guesses which files matter. With it, you direct its attention exactly where it needs to go.

@Files

Reference specific files by name.

When to use it: You know which file contains the relevant code.

Example: “Look at @auth.ts and explain how the JWT refresh logic works.”

This is the most common @ symbol. It’s fast, explicit, and prevents the AI from pulling in irrelevant files.

@Codebase

Search your entire project semantically.

When to use it: You’re not sure which files are relevant, or the answer spans multiple files you can’t easily enumerate.

Example: “@Codebase How is error handling done across this project? Show me the patterns.”

Cursor searches its semantic index, finds the most relevant code, and includes it in the context. This is powerful but uses more context window space than @Files.

@Code / @Symbols

Reference a specific function, class, or variable.

When to use it: You want to talk about one particular piece of logic, not an entire file.

Example: “Explain @validateUser and suggest how to add email verification to it.”

@Docs

Reference indexed documentation for libraries and frameworks.

When to use it: You’re working with an unfamiliar library and want the AI to reference official docs instead of guessing.

Setup: Go to Settings > Features > Docs > Add new doc, paste the library’s documentation URL. Cursor indexes it.

Example: “@Docs Express.js — How do I set up middleware for rate limiting?”

@Web

Search the web for current information.

When to use it: You need up-to-date information that might not be in your codebase or the AI’s training data.

Example: “@Web What’s the latest version of React Router and what changed in the migration guide?”

✅ Quick Check: You need to understand how your project handles authentication but you don’t know which files are involved. Should you use @Files or @Codebase? @Codebase — because you don’t know which files to reference. @Codebase will semantically search your project and find the authentication-related code across multiple files. Once you see which files matter, you can switch to @Files for follow-up questions.

The Five Context Layers

Every AI response in Cursor is shaped by five layers of context, from most persistent to most temporary:

Why this matters: If Cursor keeps ignoring your coding conventions, the fix isn’t repeating yourself in every chat message (Layer 5). It’s adding a rule (Layer 1) that applies automatically to every interaction. We’ll cover rules in detail in Lesson 6.

Context Management Best Practices

Keep conversations short. After you finish a feature or fix a bug, start a new chat with Cmd+N. Long conversations accumulate stale context that confuses the AI.

Be explicit with @. Instead of hoping Cursor finds the right files, tell it: “Look at @api/routes.ts and @middleware/auth.ts to answer this question.” Explicit context beats automatic context every time.

Don’t dump entire files. If a file is 600+ lines, reference the specific function with @Code instead of the whole file. The AI performs better with focused context.

Layer your references. For complex questions, combine @ symbols: “Using @api/routes.ts, @Docs Express.js, and the patterns in @middleware/, how should I add a new authenticated endpoint?”

✅ Quick Check: You added your team’s API documentation URL in Cursor’s docs settings. Now when you type @Docs, you see it listed. What did Cursor do with that URL? Cursor crawled and indexed the documentation at that URL. Now when you reference it with @Docs, the AI can search the actual documentation content — not just the URL. This means its answers about that API will reference real docs instead of relying on (possibly outdated) training data.

Key Takeaways

• Chat (Cmd+L) lets you have full conversations about your codebase — the AI pulls in relevant files automatically
• The @ symbol system gives you precise control: @Files for specific files, @Codebase for project-wide search, @Docs for documentation, @Code for individual functions
• Five context layers shape every response: Rules > Notepads > Docs > Files > Conversation
• Keep conversations short and start fresh for new tasks — stale context degrades quality
• Be explicit with @ references rather than hoping the AI guesses correctly

Up Next

Chat and context let you ask questions and get answers. But what if you want the AI to actually do the work — edit multiple files, run terminal commands, and fix errors automatically? In Lesson 5, you’ll learn Agent mode: Cursor’s most powerful (and most misunderstood) feature.