Context Mastery: Indexing, @Docs and @Web

How Codebase Indexing Works

When you open a project for the first time, Cursor automatically indexes it in the background. The indexer scans every file using tree-sitter, a parser that understands code structure (not just text). It extracts functions, classes, methods, module boundaries, and their relationships, and builds a semantic graph of your project.

This semantic graph is what makes @codebase work. When you use @codebase in a prompt, Cursor doesn't do a text search for your keywords — it does a semantic similarity search that finds the code most relevant to your question, even if you used different words than the code uses.

Controlling What Gets Indexed: .cursorignore

Create a .cursorignore file in your project root (same syntax as .gitignore) to exclude files and directories from the index. Common candidates:

• node_modules/ — excluded by default, but worth verifying
• dist/ or build/ — generated output adds noise with no signal
• .env files — secrets should never be in the AI's context
• Large generated files — lockfiles above a certain size, auto-generated schemas
• Binary files and media assets

A clean index means @codebase searches return higher-quality results. Including irrelevant files dilutes the semantic graph.

The Context Window Budget

Every Cursor prompt has a context window with a finite token limit. The following all count against that limit:

• The contents of rules files that are active for the current file.
• Any files, folders, or docs you added with @-symbols.
• The conversation history in the current Chat session.
• The system prompt Cursor injects automatically.

When a Chat session grows very long, earlier messages scroll out of the context window. The AI starts answering without the context it had earlier in the conversation, and output quality degrades. The fix: start a new Chat session for each new task. There is no benefit to keeping one conversation running all day — each task gets better results in a fresh context.

@docs: Giving Cursor Accurate Library Knowledge

AI models are trained on data with a cutoff date. Libraries change. React Router v7 has a different API than v6. Next.js App Router works differently than Pages Router. If Cursor's training data has an older version of a library, it will generate code that worked then but doesn't work now.

@docs solves this. You add a documentation URL, Cursor fetches and indexes the content, and that documentation becomes available as context in your prompts. Steps:

1. In Chat, type @docs
2. Select "Add new doc"
3. Paste the documentation URL (e.g., the React or Drizzle ORM docs root)
4. Cursor crawls and indexes the content
5. Type @docs in future prompts to reference it

Add @docs for every major library in your project. It is one of the most immediately impactful things you can do to improve Cursor's output quality.

@web: Live Search Mid-Conversation

@web triggers a live web search and injects the top results into your prompt context. The most practical use: paste an error message, type @web, and ask for solutions. Cursor searches the web and returns an answer grounded in current search results rather than training-data knowledge alone.

@git: Your History as Context

@git lets you reference recent git history as context. Use cases: understanding what changed recently and whether it caused a regression, summarising a branch's changes before writing a PR description, or asking why a particular decision was made based on the commit messages around it.