Cursor Context & Rules

Cursor cannot infer your repository’s conventions from a request alone. It may find code that looks relevant but belongs to a different feature, an old pattern, or a test fixture.

Context controls what the agent can inspect for one task. Rules preserve project decisions across tasks, which makes the next response easier to review. Use @ references for current evidence and .cursor/rules for durable instructions.

My Cursor work centres on cloud-agent verification, where a short committed rule outlives the chat and gives the reviewer something stable to inspect. Facts on this page were checked against official Cursor documentation on July 28, 2026.

Context Is a Selection Problem

More context does not automatically produce a better answer. A whole repository can contain several approaches to the same job, abandoned components, generated output, and tests that intentionally break rules. When Cursor receives all of it, the agent has more material to combine and more ways to choose the wrong pattern.

Start by asking what evidence the task needs. A request to change a validation message may need the form component, the schema, and one test.

A request to explain why a deployment failed may need pasted terminal output, the deployment configuration, and the changed workflow. Let the question determine the context instead of attaching everything available.

Question	Start With	Add Only If Needed
Why does this function fail?	Function and error	Caller and test
Where is this behaviour defined?	Codebase search	Relevant folder
How does this API work?	Official documentation	Local wrapper code
What changed this regression?	Current diff and test	Git history

That approach also protects private material. Do not attach secrets, production exports, or customer data just because an agent can read it.

Redact the failing value, use a minimal reproduction, or ask for a diagnostic plan before providing more detail. Context is an engineering choice and a data-handling choice at the same time.

Choose the Smallest Useful Context

Work outward from the code under discussion. Select the current function or component first, then add the test that proves its intended behaviour. Add a parent or caller only if the local code does not explain the contract.

This gives Cursor a coherent slice of the system and makes it easier for you to notice when the answer relies on something outside that slice.

For example, a request to add a loading state can start with the component, its data hook, and the closest test. If Cursor finds that the hook is shared by several screens, ask it to list those consumers before editing them.

That list turns an implicit expansion into a decision you can make.

Read the Context List Before Sending

The context picker is part of the prompt. Confirm that a selected folder did not pull in generated files, a similarly named old feature, or a private configuration file.

If the prompt contains a large codebase search result, ask Cursor to identify the files it relied on. A short answer with cited paths is easier to verify than a broad summary.

Use @ Symbols with an Intent

Cursor’s @ references are shortcuts for explicit code context. Its current context documentation names @code, @file, and @folder. The exact picker can vary by surface and version, so choose the smallest reference that matches the question.

Reference	Supplies	Best Use
@code	One code symbol	Known function or type
@file	One source file	Targeted code change
@folder	Bounded directory	One feature area
Agent search	Relevant codebase paths	Unknown implementation
Pasted output	Selected terminal text	Build or test failure

When terminal output is the evidence, paste the command with the smallest relevant failure block. Remove tokens, customer data, and unrelated logs before sending it.

Use web context cautiously for a current vendor detail, then check the primary source yourself before taking action. A search result can lead to an obsolete documentation page or a third-party explanation that does not match your installed version. For dependency, API, or price changes, attach the official documentation page and record the date you checked it.

Write Rules That Change Behaviour

A rule file is a compact set of decisions that prevents recurring mistakes. Good rules name a tool, file location, command, ownership boundary, or prohibition.

Remove vague instructions such as “write clean code.” A rule such as “use pnpm, never npm” names behaviour a reviewer can test.

Cursor’s rules documentation remains the source of truth when rule modes or file formats change.

---
description: Frontend conventions
globs: ["src/components/**/*.tsx"]
---

# Component Rules
- Use TypeScript and the existing component patterns.
- Keep tests next to the component when a test already exists there.
- Use pnpm for project commands.
- Do not add a dependency without approval.
- Do not change public props unless the task names the migration.

Each line should survive a change of ticket. Stack choices, test commands, formatting conventions, security boundaries, and folder ownership are useful.

A temporary design decision, a customer name, or the acceptance criteria for one issue belongs in the task prompt instead. If a rule stops being true, change or remove it rather than letting a stale instruction quietly win.

Write Constraints Before Preferences

Put non-negotiable constraints near the top: do not expose secrets, do not bypass authorization, do not install packages, and do not make destructive database changes without approval. Preferences such as naming style matter too, but an agent should never mistake a style request for a safety boundary.

Keep rules readable enough for a developer to challenge them in review. An instruction that cannot explain why it exists will accumulate exceptions. The best rule files act as short onboarding documents and as a record of decisions already paid for by the team.

Scope Rules to the Code They Govern

One global rule file is tempting, but it becomes noisy when a repository contains an application, infrastructure, documentation, and scripts with different conventions. Place a general project rule at the root, then add scoped rules where a local area needs extra instructions. A database folder can state migration rules without forcing that material into every UI request.

Keep overlapping rules consistent. If a local file says a convention differs from the project default, state the exception plainly.

Conflicting instructions make it difficult to tell whether Cursor ignored a rule or selected the wrong one. Test a scoped rule with a small request in the matching path before relying on it for a larger change.

• Use a root rule for package manager, tests, security, and repository-wide boundaries.
• Use a folder rule for framework or ownership details that only apply there.
• Use a task prompt for the work that must happen today.
• Delete a duplicated legacy rule once the new rule has proved itself.

Debug a Rule Before Trusting It

Test a new rule before a production migration depends on it. Make a harmless request that should visibly follow the rule. For example, ask Cursor to create a small component in the scoped folder and verify that it uses the expected test command, styling system, and file pattern.

If the response ignores a requirement, check the file path, frontmatter, scope, and current documentation.

Then inspect the generated diff. A model can repeat a rule in its explanation and still miss it in code.

The practical test is whether the changed files, command, and imports obey the convention. Rules guide the agent; they do not replace code review, command approval, or automated checks.

Keep Task Context Out of Project Rules

Rules become less useful when they turn into an issue tracker. “Use the blue button from the current mockup” and “fix ticket ABC-123” make no sense to the next person.

Put that information in the conversation, along with the exact files and checks for the task. The rule file should describe the project after the ticket is closed.

This separation makes agent sessions shorter. A new chat can begin with the immediate objective and a few selected files, while the agent already has the stable conventions from the repository. It also makes review simpler because durable instructions change in their own diff rather than slipping into an unrelated feature.

FAQ

What goes in .cursor/rules?

Put stable project conventions in .cursor/rules: language and framework choices, test commands, file patterns, security boundaries, and changes the agent must not make. Keep short-lived ticket details and one-off layout instructions in the chat. A rule should still make sense when the next developer opens the repository.

How do I reference files with @?

Type @ in a Cursor conversation and select the smallest source that can answer the task. Use @code for a known symbol, @file for one source file, and @folder when a feature spans a directory.

Ask the agent to search the codebase when you do not know the implementation. Check the included context before relying on the response.

Do rules work in Composer?

Rules can provide project context to Cursor’s AI surfaces, including Composer, when their mode and scope match the task. Verify this with a harmless test in the current Cursor version before using a rule as a security or release control. A visible diff and command approval remain separate safeguards.

Should I keep a .cursorrules file?

Use .cursor/rules files for new work because Cursor documents them as the current rules system. A root .cursorrules file may remain while you migrate, but avoid maintaining conflicting copies. Move one convention at a time, test it on a small request, then remove the duplicated legacy instruction.

What to Keep in Context

Use @ to give Cursor the smallest reliable slice of evidence for the task, and use committed rules for the conventions that should outlive that task. The combination works when both stay specific: selected files for today, verified project rules for tomorrow, and a human review for every consequential change.