Rules & Custom Instructions
Rules are persistent instructions that load automatically with every Chat message, Tab completion, and Agent task in your project. They let you define how Cursor should behave in your codebase without repeating yourself: always use TypeScript strict mode, never use class components, follow this naming convention, use our internal SDK not the third-party one.
Rule Types
Global User Rules
Set in Cursor Settings → Rules for AI. Apply to every project you open. Good for personal preferences: preferred response style, language habits, avoid emojis in code comments, always show TypeScript types.
Project Rules (.cursor/rules/)
Stored in a .cursor/rules/ directory at the repo root. Each rule is a .mdc file (MDC format — markdown with YAML frontmatter for metadata). Version-controlled alongside the code — every team member gets the same rules. Scoped to this project only. This is the recommended format as of 2026.
Team Rules
Available on Teams and Enterprise plans. Rules shared across the organization from a central admin panel — useful for enforcing company-wide coding standards or security policies without relying on each developer to have the right local rules.
AGENTS.md
A plain markdown file in the repo root (or any subdirectory). Simpler than .mdc files — no metadata, no frontmatter, just instructions. Good for projects where you want readable instructions without the overhead of structured rules. Subdirectory AGENTS.md files apply only when the agent is working in that directory or its children.
The .mdc File Format
MDC (Markdown with Cursor metadata) files live in .cursor/rules/ and look like this:
--- (frontmatter)
description: TypeScript conventions for this project
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---
# TypeScript Rules
- Always use strict TypeScript (no `any`)
- Prefer `interface` over `type` for object shapes
- Use named exports, not default exports
- All async functions must handle errors explicitly
The globs field scopes the rule to specific file patterns. alwaysApply: true loads the rule into every context regardless of which file is open. alwaysApply: false (default) only applies when the open file matches the glob.
Legacy .cursorrules
Earlier versions of Cursor used a single .cursorrules file at the repo root. This format still works but is deprecated — Cursor will continue to read it, but the current recommendation is to migrate to .cursor/rules/*.mdc. The new format gives you finer-grained control: multiple rules, glob scoping, and per-rule metadata.
Best Practices
What works well in rules
- • Naming conventions (“use kebab-case for filenames”)
- • Library choices (“use Zod for validation, not Yup”)
- • Testing standards (“always add unit tests for new service methods”)
- • Output format preferences (“use early returns, avoid nested ifs”)
- • What NOT to use (“never use moment.js, use date-fns”)
What doesn't work well
- • Very long rules (hundreds of lines — only the most relevant parts load)
- • Vague instructions (“write good code”)
- • Rules that duplicate what's obvious from the codebase
- • Outdated rules that contradict how the code actually works
Rules evolve with the project. When you find yourself correcting Cursor on the same point three times in a row, that's a signal it belongs in a rule file.
Checklist: Do You Understand This?
- Rules apply automatically to every Chat, Tab, and Agent interaction — no need to repeat instructions each session
- Three scopes: Global User Rules (all projects), Project Rules (.cursor/rules/*.mdc), Team Rules (org-wide on Teams/Enterprise)
- AGENTS.md is a simpler alternative to .mdc — plain markdown, works in root or subdirectories
- .cursorrules still works but is deprecated — migrate to .cursor/rules/ for new projects
- Use glob scoping to apply rules only to relevant file types