Cursor Rules: Persistent Context for Your AI Agent
I spent months repeating the same instructions to Cursor at the start of every conversation. Document in Portuguese. Use conventional commits. Follow the Plan → Work → Review loop. Every session, the same manual onboarding.
That is a design problem, not an inevitable limitation. Rules are the mechanism for injecting persistent context into the agent before it responds to the first word.
The problem
An AI agent operating with no project context is like hiring a senior consultant and skipping the onboarding.
It makes decisions that are technically correct but contextually wrong: English where the project documents in Portuguese, commits without conventional prefixes, files in PascalCase where the project uses kebab-case.
The teams who suffer most are the ones with well-defined standards — they lose consistency every time a new conversation starts.
Anatomy of a rule
Rules are .mdc files in .cursor/rules/, with YAML frontmatter and a Markdown body:
---
description: "Project conventions for documentation and commits"
globs: []
alwaysApply: true
---
# Compound Engineering Workflow
- Documentation in pt-BR, code in English
- Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore:
- Mandatory loop: Plan → Work → Review → Compound
Three activation modes
alwaysApply: true loads on every conversation without exception. Use it for universal conventions — language, commit style, working loop. The cost is that it consumes context tokens every time, even when irrelevant.
Glob-scoped (globs: ["*.rb", "app/**/*.rb"]) activates when a matching file is open. Ideal for language-specific patterns, frameworks, or a particular application layer.
Manual (@rules/name) is invoked explicitly. For narrow rules that only matter in specific situations.
Why not the alternatives
Repeating context in a custom system prompt doesn't scale, isn't versioned with the project, and is hard for multiple developers to maintain.
Putting everything in one giant rule loses modularity. A 2,000-token rule consumed on every conversation that only needed 200 tokens is wasted context.
Code comments are read by the agent but aren't reliable as a source of truth for convention.
What it costs
You gain cross-conversation consistency with no manual effort, onboarding for new team members through the rules themselves, and context versioned alongside the code.
You accept that alwaysApply rules consume tokens on every conversation — in projects with many rules, that context cost climbs. And rules aren't dynamic: when a convention changes, you edit the file by hand.
How it fails
Conflicting rules. Two alwaysApply rules establishing opposite standards. The agent will try to reconcile them, or prioritize whichever loaded last, non-deterministically.
The warning sign: the agent starts ignoring standards you know are in a rule. Usually that means either a conflict between rules, or the conversation grew long enough that the rule was pushed out of the attention window.
Over-specification. A rule so detailed it covers too many edge cases and becomes internally contradictory. A rule should cover one specific domain, not every possible case.
Staleness. The project evolved and the rule didn't, so the agent follows the old convention. Treat rules as code: review them, update them alongside refactors.
What I learned
Start with fewer rules and add them as you spot real inconsistencies. Don't try to anticipate everything — a rule written to solve an actual problem is more effective than one written preventively.
AGENTS.md and .cursor/rules/ serve different audiences: CLI agents versus the IDE agent. In projects using both, keep both — but don't copy-paste. Each should carry the level of detail its consumer needs.
And most importantly: a rule existing does not mean the agent follows it 100% of the time. Rules reduce inconsistency; they don't eliminate it. Treat them as probabilistic, not deterministic, and calibrate as you observe actual behavior.