Skip to content
AgentAtlas

Cursor rules setup: project, user and Team Rules, .mdc frontmatter, globs and AGENTS.md

How do I add project rules in Cursor?

Create .mdc files in your repo's .cursor/rules folder, each with frontmatter that sets description, globs and alwaysApply. The fastest way is to type /create-rule in Agent chat. For plain markdown with no metadata, use an AGENTS.md file instead.

Also in: 简体中文 · 日本語 · 한국어 · Español · Português (Brasil)

Compare: rules and instruction files in every AI coding agent →

Where rules live

  • Project Rules: .mdc files in .cursor/rules. They are version controlled and scoped to the codebase. Subfolders are supported.
  • User Rules: global preferences set in Cursor's rules settings. They apply across all projects.
  • Team Rules: managed from the Cursor dashboard on Team and Enterprise plans.
  • AGENTS.md: plain markdown instructions with no metadata.

Project rules must use the .mdc extension. A plain .md file in .cursor/rules is ignored by the rules system.

Frontmatter and rule types

  • Always Apply: alwaysApply: true. Included in every chat session.
  • Apply to Specific Files: alwaysApply: false plus globs. Attached when a matching file is in context.
  • Apply Intelligently: alwaysApply: false plus description, no globs. Agent pulls it in when relevant.
  • Apply Manually: no description or globs. Used only when you @-mention it.

Separate multiple glob patterns with commas. For example, src/**/*.tsx matches .tsx files under src/.

Example rule files

.cursor/rules/components.mdc

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports
- Keep components under 200 lines
- Prefer composition over prop drilling

.cursor/rules/general.mdc

---
alwaysApply: true
---

- Read the relevant source files before proposing changes
- Never modify generated files in dist/ or build/

An @file reference inside a rule tells Agent where to look. The file is not inlined, so put anything that must always be in context in the rule body.

Team Rules

  • Available on Team and Enterprise plans. Admins create and manage them in the Cursor dashboard.
  • Team Rules are free-form text and do not use the .cursor/rules folder structure.
  • Each rule can be enforced or optional. Users can turn off a non-enforced Team Rule under Team Rules in Customize. An enforced rule cannot be disabled there.
  • A rule with a glob pattern applies only when matching files are in context. A rule without a glob applies to every conversation.
  • Leave the enable box unchecked to save a rule as a draft that does not apply until you enable it.
  • Enabled Team Rules are included in Agent (Chat) context across all of the team's repositories and projects.

Cursor notes that AI guidance should not be your only security control, even for enforced rules.

AGENTS.md and nested instructions

Put AGENTS.md in the project root. Nested AGENTS.md files in subdirectories apply when working in that directory. They combine with parent files, and the more specific file wins.

Precedence and limits

  • Precedence is Team Rules, then Project Rules, then User Rules. All rules merge, and earlier sources win on conflicts.
  • User Rules apply only to Agent, not to Inline Edit.
  • Rules do not affect Cursor Tab.
  • Keep each rule under 500 lines and split large ones into smaller rules.

Sources

More Cursor guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →