The Workshop · 12 min mission

Cursor Rules & Context: Teaching Cursor Your Codebase

Make Cursor's agent follow your conventions every session — and pull in the right context on demand.

cursoride-agentsrulescontextmdcagents-mdcodebase-indexingFact-checked 2026-06-15

On this page

The four rule types
Scope precedence: Team → Project → User
AGENTS.md: the no-frontmatter alternative
@-symbols: on-demand context
Codebase indexing: semantic vs grep search

This guide covers Cursor 3.7's two context mechanisms with exact paths, fields, and commands: rules — version-controlled instructions in .cursor/rules/*.mdc and AGENTS.md injected at the start of the model context — and on-demand context — @-symbols and codebase indexing the agent fetches per task. After it you can author a rule with the right firing type, set the Team/Project/User scope, and pull files, diffs, and search results into a prompt.

Create a project rule

Generate the file from Agent
In Agent, type /create-rule and describe what you want. Cursor generates the rule with valid frontmatter and saves it to .cursor/rules. (You can also use Cursor Settings → Rules → + Add Rule.)
Pick the type from the dropdown
The type dropdown writes the alwaysApply, description, and/or globs frontmatter for you (see the table below). If you hand-write the .mdc file, set those fields yourself. The file extension must be .mdc, not .md.
Keep it focused and commit
Official guidance: keep each rule under 500 lines and split a large rule into multiple composable rules. Group related rules into subdirectories of .cursor/rules. Then commit the .mdc files so the repo shares the conventions.

.cursor/rules/frontend-components.mdc

---
description: "Standards for React frontend components"
globs: src/components/**/*.tsx
alwaysApply: false
---
 
- Components are function components with named exports; no default exports.
- Co-locate styles in a sibling .module.css file.
- Prefer composition over prop-drilling; lift shared state to a context.
 
See @src/components/Button.tsx for the canonical pattern.

The four rule types

The frontmatter exposes exactly three fields — description, globs, and alwaysApply. The type dropdown sets a combination of them, and the combination determines whether the rule ever fires. globs accepts comma-separated patterns (e.g. src/components/**/*.tsx, src/pages/**/*.tsx).

Type	Fires when	Frontmatter
Always Apply	Every chat session, unconditionally	`alwaysApply: true`
Apply Intelligently	Agent reads `description` and decides relevance	`alwaysApply: false` + `description`, no `globs`
Apply to Specific Files	An edited/referenced file matches a glob	`alwaysApply: false` + `globs`
Apply Manually	You `@`-mention the rule by name	`alwaysApply: false`, no `description`/`globs`

The four rule-type dropdown names in Cursor 3.7 and the frontmatter each writes.

Build the .mdc frontmatter from a rule type

Write your rules once, ship them everywhere

Every coding agent reads its rules from a different file with its own conventions. Write your project rules once below — then switch tabs to get each tool's native format, ready to copy.

Project name (optional)Project rules (one per line)5 rules parsed.

./AGENTS.md

# AGENTS.md

## Project overview

Acme Dashboard

## Conventions

- Use TypeScript strict mode — no `any`, no implicit returns

- Run the full test suite before opening a pull request

- Never commit secrets; .env stays out of version control

- Prefer small, focused modules over sprawling files

- Match the existing code style; let the formatter decide the rest

Pick a firing behavior — always / by glob / by agent judgment / on `@`-mention — and see the `alwaysApply` / `globs` / `description` combination, plus how the same instructions map to `AGENTS.md`.

Scope precedence: Team → Project → User

Cursor recognizes three rule scopes. All applicable rules are merged and applied in a fixed precedence order, with earlier sources winning on conflict:

Team Rules → Project Rules → User Rules.

Team Rules — organization-wide, managed from the Cursor dashboard. When enabled, a team rule is required for all members and cannot be disabled in individual Cursor settings; an unchecked rule is saved as a draft.
Project Rules — the .cursor/rules/*.mdc files, version-controlled and scoped to the repo.
User Rules — global preferences set in Cursor Settings → Rules. They apply to Agent (Chat) only — not Tab autocomplete and not Inline Edit.

Remote/imported rules are a delivery mechanism, not a fourth scope: in Cursor Settings → Rules use Add Rule → Remote Rule (Github), paste a repo URL, and Cursor imports its .mdc files into .cursor/rules/imported/<repoName> (preserving their relative paths).

AGENTS.md: the no-frontmatter alternative

AGENTS.md is a plain Markdown file (no frontmatter) placed in the project root, read by Cursor as an alternative to .cursor/rules for straightforward cases. It nests: an AGENTS.md in any subdirectory applies automatically to files in that directory and below, and nested instructions combine with parent directories — the more specific (more local) file takes precedence. The Cursor CLI (cursor-agent) also reads both AGENTS.md and CLAUDE.md at the project root and applies them as rules alongside .cursor/rules, so a repo carrying a CLAUDE.md for Claude Code is picked up for free.

Mechanism	Location	Firing	Reach for it when
`.cursor/rules/*.mdc`	`.cursor/rules/` (committed)	Always / glob / agent judgment / `@`-mention	You need conditional rules (e.g. load only when editing `api/**`)
`AGENTS.md`	Project root or nested per-dir	Always-on (closest file wins)	You want one always-on brief that travels across tools
`CLAUDE.md`	Project root	Always-on, CLI only (`cursor-agent`)	A repo already has a `CLAUDE.md` and you run the Cursor CLI

Pick the mechanism by what firing behavior you need.

@-symbols: on-demand context

Rules load automatically; @-symbols attach specific context to a single prompt. The "Prompting agents" doc enumerates exactly this set:

Symbol	Injects
`@Files` & `@Folders`	Specific files/folders; type `/` after a folder to navigate deeper
`@Docs`	Indexed documentation; `@Docs > Add new doc` adds one by URL
`@Terminals`	Terminal output as context
`@Past Chats`	Summarized context from a previous conversation
`@Commit (Diff of Working State)`	Your uncommitted changes
`@Branch (Diff with Main)`	The full branch diff vs. `main`
`@Browser`	Context from Cursor's built-in browser

The documented `@`-symbols on cursor.com/docs/agent/prompting (Cursor 3.7).

Codebase indexing: semantic vs grep search

On opening a workspace, Cursor splits code into meaningful chunks (functions, classes, logical blocks), creates a vector embedding per chunk, and stores them in a vector database. A query is embedded with the same model and matched against those vectors. Two search modes sit on top, and the agent auto-selects between them — specific symbols lean on grep; fuzzy concepts start with semantic search. Manage status and re-indexing from Cursor Settings → Indexing.

Item	Detail
Semantic search	Find code by meaning when the name is unknown ("where do we validate webhooks?")
Grep / Instant Grep	Exact matching with full regex and word boundaries
Availability	Semantic search becomes available at 80% completion
Sync	Index auto-syncs every 5 minutes, processing only changed files
Exclusions	Skips files matched by `.gitignore` and `.cursorignore`
Privacy	Paths encrypted before transmit; no filenames/source stored; chunks decrypted client-side on search

The two search modes and the indexing/privacy facts behind them.

Opening a large repo, cold

… scroll to run this session

Semantic search lights up at ~80% completion and the index syncs every 5 minutes, so right after opening a big repo the agent falls back to grep and may not see the newest files yet.

Knowledge check

You wrote a rule full of React conventions, set its type to "Apply Intelligently", and gave it the description "react". The agent keeps ignoring it on component work. What is the most likely fix?

Reach the end and this star joins your charted sky.