Cursor rules: project conventions the agent follows

Where rules live

Cursor reads instructions from several places, and they stack rather than compete. Knowing which is which saves you writing the same convention into two of them.

.cursor/rules/
  conventions.mdc      alwaysApply: true, keep it under 20 lines
  react.mdc            globs: src/ui/**/*.tsx
  api.mdc              globs: src/api/**/*.ts
  migrations.mdc       description only, the agent decides
  release.mdc          no description, no globs, manual only
AGENTS.md              the cross-tool file, read by Cursor and others

The MDC format

A project rule is a Markdown file with an .mdc extension and YAML frontmatter. There are three frontmatter fields, and the combination you set decides when the rule fires.

---
description: React component conventions for this project
globs: ["src/ui/**/*.tsx", "src/ui/**/*.ts"]
alwaysApply: false
---

- Function components only. No classes.
- Props interfaces are named ComponentNameProps and are exported.
- No inline styles. Use the token classes in src/ui/tokens.css.
- Data fetching lives in hooks under src/hooks/, never inside a component.
- Every interactive element needs an accessible name. No exceptions.
- Example to copy: src/ui/Button.tsx

Choosing a rule type

A good shape for most repositories is one short always-on file with the four or five things that are true everywhere, then glob-scoped rules per area. That way a TypeScript component edit never carries your Go conventions, and your Go files never carry the accessibility rules for React.

Cursor advises keeping rules under 500 lines and splitting anything larger into multiple composable rules, referencing external files rather than duplicating their content. Treat 500 as the hard ceiling and 30 as the target: a rule you can read in ten seconds is a rule you will keep accurate. Its own guidance is blunter still, and correct: start simple, and add a rule only when you notice the agent making the same mistake repeatedly.

Writing rules that change behaviour

• Be specific enough to check. If you cannot tell from a diff whether the rule was followed, it is not a rule, it is a mood.
• Say what is forbidden, not only what is preferred. Prohibitions survive paraphrase; preferences do not.
• Point at an example in the repository. One file path is worth a paragraph of description.
• Keep each file short and single-concern. One file for styling, one for testing, one for API conventions.
• Delete rules that stopped being true. A stale rule actively degrades output, because the agent follows it.

When a rule is being ignored

Almost always the trigger, almost never the wording. Work down this list.

AGENTS.md and the cross-tool problem

Cursor reads AGENTS.md from the project root and from subdirectories, as plain markdown with no frontmatter, and nested files combine with their parents so the more specific instruction wins. That matters because AGENTS.md is the file the rest of the ecosystem reads too, so it is the only place a convention can be written once for every agent that touches the repository.

To migrate off .cursorrules: create a new rule from the command palette, paste the old content in, set the type to Always Apply so it matches the previous behaviour, then delete the file from the project root. Do it as one commit so the review shows the move rather than a mystery deletion.

Questions people ask

Keep reading