Cursor Project Rules (.cursor/rules/*.mdc): where it lives and how tools read it

Cursor Project Rules are .mdc files in .cursor/rules/ whose frontmatter decides when each rule is attached. Cursor also reads AGENTS.md, plus User Rules and Team Rules set outside the repository.

Where it lives

• .cursor/rules/**/*.mdc, subfolders allowed; plain .md files in .cursor/rules are ignored.
• AGENTS.md at the root and in nested folders.
• User Rules, set in Cursor settings.
• Team Rules, set in the team dashboard.

Format

Markdown with YAML frontmatter, and the .mdc extension is required. alwaysApply: true always includes the rule; globs with alwaysApply: false attach it when a matching file is in context; a description alone lets the Agent decide. With none of these, the rule applies only when you @-mention it.

Frontmatter keys: descriptionglobsalwaysApply

---
description: React component conventions
globs: src/components/**/*.tsx
alwaysApply: false
---

- One component per file, with a named export matching the file name.
- Type props with an interface named after the component plus Props.
- Use the existing CSS modules; no inline style objects.
- Follow @src/components/Button.tsx as the reference pattern.

Precedence and merging

Team Rules, then Project Rules, then User Rules. All applicable rules are merged, and the earlier source wins on conflict; enforced Team Rules can't be switched off. Nested AGENTS.md files combine with their parents, with the more specific file winning.

Tools that read it

Tips

• Separate several globs with commas in the globs field.
• Keep each rule under 500 lines and reference files with @filename instead of pasting them.
• Rules don't affect Cursor Tab, and User Rules don't apply to Inline Edit.
• The legacy .cursorrules file is no longer mentioned in Cursor's docs; move it into .cursor/rules/.

Other instruction files