How to Give Cursor Better Context with @ Mentions and Rules

Agent can search your repository, but search alone does not know your team conventions, which files are canonical examples, or which directories are off limits. Two mechanisms focus Agent quickly: @ mentions in the Agent input for files and folders you already know matter, and rules that inject persistent instructions at the start of model context for Ask, Agent, Plan, and Debug.

Rules do not apply to Tab completion or inline edit. Tab uses recent edits and linter signals only. Explore summary at /explore/cursor under Context with @ mentions and rules.

The context workflow

Before a non trivial Agent task, choose relevant files, attach them with @, confirm project or team rules cover repeated conventions, state constraints and non goals in the prompt, then verify the diff stays inside scope. Writing a rule once beats pasting the same paragraph in every chat.

@ mentions in the Agent input

Type @ to attach a file, folder, doc, or rule. Attach the module under change plus one reference that shows the pattern to copy. Avoid attaching the entire repository; too many files dilute attention.

@src/app/api/users/route.ts @src/lib/db.ts
Add pagination to GET /users using existing query helpers in db.ts.
Response shape must match @src/app/api/products/route.ts.
Do not change database schema.

@src/features/billing/
Fix the proration bug described below.
Do not edit src/features/payroll/ or payment provider SDK wrappers.
Done when: billing.proration.test.ts passes.

Folder level @ vs single file @

Use @src/features/billing/ when the task spans that feature but should not touch other packages. Use a single file @ when the change is localized. Combine one folder plus one reference file outside the folder when Agent needs both scope and pattern.

@src/features/reports/ @src/app/api/export/route.ts
Add PDF export alongside CSV in reports feature only.
Match auth checks from export route.
Done when: reports.export.test.ts passes.

@ mentions in Ask vs Agent

Ask mode uses @ the same way to focus explanation. Agent mode uses @ to prioritize edits. In both cases, fewer attachments beat a long list of every file Agent might need.

Project rules in .cursor/rules

Project rules live in .cursor/rules as .mdc files with frontmatter. Rule types include Always Apply, Apply Intelligently with a description, Apply to Specific Files with globs, and Apply Manually when @ mentioned. Keep each rule focused under roughly five hundred lines. Point to canonical files instead of copying entire style guides. You can create rules from Customize in the sidebar or ask Agent to run /create-rule in chat.

Example: glob scoped rule for components

# .cursor/rules/react-components.mdc frontmatter concept
globs: src/components/**/*.tsx
alwaysApply: false

- Use named exports for components
- Co locate tests as Component.test.tsx
- Reference @src/components/Button.tsx for prop patterns

Example: manual rule invocation

@migration-rule
Add migration 20260822_add_invoice_status.sql
Follow template in @db/migrations/TEMPLATE.sql
Include down migration.

Ignore files and sensitive paths

Cursor supports ignore files that limit indexing scope. Pair ignore rules with prompt level do not touch lists for secrets and generated output. Rules should reference where env vars live without pasting secret values.

Agent: @src/config/
Document required env vars in README internal section.
Do not read or print .env or .env.local contents.
Do not commit secrets.

AGENTS.md for readable instructions

AGENTS.md is plain markdown in the project root or nested folders. Use it when you want simple readable instructions without rule frontmatter. Nested AGENTS.md files apply when you work in that folder and combine with parent instructions, with more specific files taking precedence.

# AGENTS.md (project root excerpt)
## Tests
Run npm test -- --testPathPattern=<module> for focused runs.
Do not commit failing tests.

## Scope
Prefer changes under src/features/<name>/ unless the task requires shared libs.

User rules and team rules

User rules in Customize apply across all projects for Agent chat preferences. Team rules on Teams and Enterprise plans publish from the Cursor dashboard. Enforced team rules cannot be disabled by members. Precedence on conflicts is team rules first, then project rules, then user rules.

@api-routes-rule
Implement POST /api/refunds using team billing conventions.
@src/app/api/charges/route.ts as reference.
Done when: refunds.route.test.ts passes.

Combine @ mentions with explicit do not touch lists

@src/lib/checkout/calculateTotal.ts
Fix rounding for tax inclusive prices.
Do not edit: src/lib/payments/stripeClient.ts, prisma/schema.prisma
Verify: npm test -- --testPathPattern=calculateTotal

Common mistakes

• Repeating conventions in every prompt instead of writing a rule once
• Attaching ten files when two would focus Agent
• Expecting rules to steer Tab completion
• Pasting secrets into chat instead of using environment docs in rules
• Copying entire files into rules instead of referencing paths with @

Verification after a scoped Agent task

• Diff only touches allowed paths
• Patterns match the reference file you named
• Tests cover the changed behavior
• No unrelated formatting sweeps across the repo

MCP servers and external context

MCP servers can expose issue trackers or internal docs to Agent in supported setups. They complement @ file attachments when the source of truth lives outside the repo. Rules still define how Agent should interpret external data.

Maintaining rules over time

Update rules when Agent repeats the same mistake twice. Check rules into git so the team shares them. Remove stale rules that reference deleted files. Prefer pointing @ at canonical examples that stay current.

Agent: update api routes rule to reference @src/app/api/orders/route.ts
Old reference src/app/api/v1/orders.ts was removed.

Layering user rules with project rules

User rules might ask for concise replies while project rules define code patterns. Both apply to Agent modes. When they conflict, team rules override on Teams plans, then project rules, then user rules per Cursor docs.

User rule: prefer bullet summaries before code.
Project rule: always add tests beside new API routes.
Agent task: implement POST /api/notes with both conventions.

Creating rules from chat

Run /create-rule in Agent when you notice a repeated instruction. Describe the convention in plain language and let Agent write the .mdc file with frontmatter. Review the rule file in git like any other change.

/create-rule
Name: api-routes
When: editing src/app/api/**
Require: zod validation at boundary and test file beside route

Remote rules from GitHub

Import rules from a GitHub repository through Customize when your organization maintains shared conventions centrally. Imported rules land under .cursor/rules/imported/ and keep relative paths. Review imports on upgrade the same way you review dependency updates.

After importing org rules, run Agent on @src/app/api/new-feature/
Confirm responses follow imported api standards rule.
Adjust local AGENTS.md only for repo specific exceptions.

Keeping AGENTS.md current

AGENTS.md at the repo root gives Agent a quick orientation. Update it when stack choices change, when you add a new test command, or when folder layout shifts. A stale AGENTS.md sends Agent to wrong directories. Keep it short: commands to run, folder purposes, and conventions that must not be broken.

AGENTS.md snippet to maintain:
Test: npm test
Lint: npm run lint
App routes live under src/app/
API routes under src/app/api/
Never commit .env values

Rules when the codebase changes

After a major refactor, audit rules that reference old paths or deprecated patterns. A rule pointing at src/pages when the app moved to App Router will confuse Agent for months. Delete obsolete rules instead of stacking contradictions. One clear rule beats three overlapping ones.

When onboarding a teammate, ask them to run one small Agent task on day one. If Agent violates a convention, add or tighten a rule immediately. Rules grow from real mistakes, not from guessing every edge case upfront.

Related: /blog/how-to-use-cursor-agent-to-build-and-refactor-code, /blog/how-to-test-and-verify-changes-made-by-cursor, /blog/cursor-ask-vs-agent-vs-plan-which-mode-should-you-use.