Cursor rules vs AGENTS.md

Quick answer

• Use `AGENTS.md` for plain, always-relevant project instructions (setup, test and lint commands, code style). It is an open format that many coding agents read, and Cursor reads it in your project root and in subfolders.
• **Use .cursor/rules/*.mdc** when you need Cursor to apply an instruction only sometimes: for certain file patterns, when the agent judges it relevant, or only when you @-mention it.
• Don't start with `.cursorrules`. Cursor calls it legacy and says it will be deprecated. If you have one, migrate it.
• Using several agents? Put the shared basics in AGENTS.md and keep Cursor-specific, file-scoped rules in .cursor/rules.

The three options at a glance

• Project rules: .mdc files in .cursor/rules/. Cursor-only. YAML frontmatter controls when each rule loads. Supports folders and globs.
• AGENTS.md: one markdown file with no required fields or frontmatter. Cross-tool. Nested files in subfolders apply to that part of the repo.
• .cursorrules: a single file in the project root. Legacy. Always-on behaviour only, with no scoping.

Cursor also has User Rules (your personal preferences across projects, set in Customize) and Team Rules (managed from the dashboard on Team and Enterprise plans). Cursor applies them in this order when guidance conflicts: Team Rules, then Project Rules, then User Rules.

Cursor project rules (.cursor/rules)

Project rules live in .cursor/rules as .mdc files and are meant to be committed to git. The extension matters: Cursor's docs say a plain .md file in that folder is ignored because it has no frontmatter. Folders inside .cursor/rules are fine.

.cursor/rules/
  react-patterns.mdc      # recognized
  api-guidelines.md       # ignored (wrong extension)
  frontend/
    components.mdc        # recognized

Three frontmatter fields decide when a rule is included:

• alwaysApply: true: included in every chat session. Globs and description are ignored.
• globs set and alwaysApply: false: attached automatically when a matching file is in context (Apply to Specific Files).
• description set, no globs, alwaysApply: false: the agent reads the description and pulls the rule in when relevant (Apply Intelligently).
• None of them: the rule is only used when you @-mention it in chat (Apply Manually).

A rule that applies only to React components:

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

- Use named exports, not default exports
- Co-locate styles in a module CSS file next to the component
- Keep components under 200 lines

A rule the agent can choose to load, plus a file reference. Cursor's docs note that @template.ts tells the agent where to look; the file is read when needed, not pasted into the prompt:

---
description: RPC service conventions and patterns for the backend
alwaysApply: false
---

- Define each service in its own file under `src/services/`
- Validate inputs at the service boundary
- Read `@service-template.ts` before creating a new service

Create one by typing /create-rule in Agent chat, or open Customize, go to Rules and click Add Rule. Cursor's tips: keep each rule under 500 lines, split big ones into smaller composable rules, point to example files instead of copying code, and add a rule only after you see the agent make the same mistake more than once. Rules don't affect Cursor Tab or other AI features.

AGENTS.md

AGENTS.md is an open format described at agents.md as "a README for agents". It is plain markdown with no required fields: headings are up to you. The agents.md site is stewarded by the Agentic AI Foundation under the Linux Foundation. A typical file:

# AGENTS.md

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons

How Cursor treats it

Cursor supports AGENTS.md in the project root and in subdirectories. Nested files are combined with their parents, and the more specific one wins when instructions conflict. Cursor describes it as a simple alternative to .cursor/rules for straightforward cases: no metadata, no globs, no rule types.

project/
  AGENTS.md              # global instructions
  frontend/
    AGENTS.md            # frontend-specific
  backend/
    AGENTS.md            # backend-specific

Which tools read AGENTS.md

The agents.md site lists these among supported tools: Codex, Jules, Factory, Aider, goose, OpenCode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Windsurf, Augment Code and GitHub Copilot's coding agent. Two are worth knowing about:

• Claude Code reads AGENTS.md too, but only when your project has no CLAUDE.md (or CLAUDE.local.md) in the working directory or above it, and it needs Claude Code v2.1.277 or later. If you have both, it reads CLAUDE.md only, unless you change the Project instructions setting in /config.
• Aider and Gemini CLI need a one-line setting pointing at AGENTS.md; the agents.md FAQ shows each one.

See Codex CLI, OpenCode and Claude Code for those tools.

Conflicts

Per agents.md, the closest AGENTS.md to the file being edited wins, and explicit instructions you type in chat override everything.

.cursorrules (legacy)

The .cursorrules file in your project root is the original format. Cursor's help center calls it legacy and says it will be deprecated. In March 2026 a Cursor team member said on the forum that it should still work for now, but that .cursor/rules is the actively supported format, and that when both exist the .mdc rules take precedence where they overlap. Treat it as something to move off, not build on.

Migrate it

1. Create a new rule: open the command palette and run New Cursor Rule (or use /create-rule).
2. Copy the contents of .cursorrules into the new rule.
3. Set the rule type to Always Apply, which matches the old behaviour.
4. Delete .cursorrules from your project root.

If the instructions aren't Cursor-specific, you could put them in AGENTS.md instead and skip the rule file.

When to use which

• One small project, only Cursor: either works. AGENTS.md is faster to write; a single always-apply rule is equivalent.
• Team uses Cursor plus Claude Code, Codex or another agent: AGENTS.md for the shared facts, so nobody maintains duplicate files.
• Different conventions for different file types (React components versus SQL migrations): .cursor/rules with globs. AGENTS.md has no way to scope by file pattern, other than nesting by folder.
• A long reference the agent should only load when relevant: an Apply Intelligently rule with a good description.
• A checklist you want to trigger by hand (release steps, migration template): an Apply Manually rule you @-mention.
• Personal preferences such as reply style: User Rules, not the repo.

Using both

Cursor loads both, so a common setup is a short AGENTS.md for commands and conventions plus a few scoped .mdc rules. Avoid saying the same thing in both places: if the two disagree you're leaving the agent to guess. To keep a single source of truth for Claude Code as well, Anthropic's docs suggest a CLAUDE.md that imports AGENTS.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

A symlink (ln -s AGENTS.md CLAUDE.md) also works if you need no Claude-specific content, but Anthropic notes the import is safer on Windows.

What to put in either one

• Exact commands: install, build, test, lint, and how to run a single test.
• Conventions the agent can't infer from the code, such as naming and folder layout.
• Hard rules: files that are generated, directories not to touch, checks to run before finishing.
• Pointers to canonical example files rather than copied code.

Cursor's docs advise against pasting whole style guides (use a linter), documenting every common command, and covering rare edge cases. Instructions are guidance for the model, not enforcement: for hard security limits, use permissions and review rather than a rules file.

FAQ

Does Cursor read AGENTS.md?

Yes. Cursor supports AGENTS.md in the project root and in subdirectories.

Should I replace .cursor/rules with AGENTS.md?

Only if you don't need scoping. Rules can attach by glob, by description or by @-mention; AGENTS.md is always plain instructions.

Can I use .md files in .cursor/rules?

No. Cursor's docs say project rules must use the .mdc extension and a plain .md file there is ignored. If you prefer plain markdown, use AGENTS.md.

Why isn't my rule applying?

Check the rule type. For Apply Intelligently, make sure a description is set. For Apply to Specific Files, make sure the glob matches the files in context.

Do rules apply to Cursor Tab?

No. Cursor says rules don't impact Cursor Tab or other AI features.

Setting up MCP servers too?

MCP servers are configured separately in mcp.json. See how to add an MCP server to Cursor.