Guide
Cursor rules: .mdc files, apply modes and AGENTS.md in 2026
Cursor rules are reusable instructions placed at the start of the model context. Project rules live in .cursor/rules as version-controlled .mdc files with description, globs and alwaysApply frontmatter. Cursor also supports User Rules (global), Team Rules (set from the dashboard, Team or Enterprise plans) and AGENTS.md.
Our atlas has two profiles for Cursor rules: the official cursor-rules documentation and agents-md, an open plain-Markdown format that Cursor, Codex, Gemini CLI and Windsurf can read. The Cursor docs recommend keeping rules under 500 lines, and plain .md files inside .cursor/rules are ignored.
- Official 2
How it works
- Type /create-rule in Agent chat and describe the rule, or open Customize > Rules > Add Rule.
- The rule is saved to .cursor/rules/<name>.mdc; set description, globs and alwaysApply in the frontmatter.
- Four apply modes exist: Always, Intelligently (by description), Specific Files (by globs) and Manual (@-mention).
- Commit the .cursor/rules folder so the whole team shares the same rules.
- For a simpler setup, put an AGENTS.md at the repo root; nested AGENTS.md files serve monorepo packages and the closest one wins.
What a rules file looks like
An .mdc rule has frontmatter (description, globs, alwaysApply) and plain-text instructions. AGENTS.md has no frontmatter and is read by several agents, not only Cursor.
File: .cursor/rules/<name>.mdc (project) · AGENTS.md (repo root)
---
description: How we write React components in this repo
globs: ["src/**/*.tsx"]
alwaysApply: false
---
- Use function components and hooks; no class components.
- Co-locate tests as <Component>.test.tsx.
- Never import from `../../..`; use the `@/` alias.---
globs: src/components/**/*.tsx
alwaysApply: false
---
- Use named exports, not default exports{
"context": {
"fileName": "AGENTS.md"
}
}The list (2)
| Name | Author | Works with | License | Status | Source |
|---|---|---|---|---|---|
| AGENTS.md Open Markdown format that gives coding agents project instructions, a README for agents r… |
AGENTS.md (Agentic AI Foundation, Linux Foundation) official | OpenAI Codex, Cursor, Gemini CLI, Windsurf | — | maintained | agents.md ↗ |
| Cursor Rules Persistent prompt-level instructions for Cursor Agent: project .mdc rules, user rules, te… |
Cursor (Anysphere) official | Cursor | — | maintained | cursor.com ↗ |
Frequently asked questions
Where do Cursor rules go?
In .cursor/rules as .mdc files. Plain .md files in that folder are ignored; use .mdc or AGENTS.md.
What are the Cursor rule apply modes?
Always, Intelligently (chosen by the description), Specific Files (matched by globs) and Manual (called with an @-mention).
Should I use AGENTS.md or .cursor/rules?
AGENTS.md is a simpler plain-Markdown alternative that other agents also read. .cursor/rules gives you frontmatter control over when each rule applies.
Can rules enforce a policy?
No. AGENTS.md is guidance text, and explicit chat prompts override it. Cursor's docs suggest a linter instead of pasting whole style guides into rules.