Cursor rules vs AGENTS.md
Checked against the official docs: Oct 27, 2026
Cursor gives you three ways to hand your coding agent standing instructions: project rules in .cursor/rules, an AGENTS.md file, and the older .cursorrules file. They overlap, and they work differently. This guide explains each one, which tools read it, and which to pick, with copy-paste examples checked against Cursor's docs and the agents.md site.
Quick answer
-
Use
AGENTS.mdfor 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/*.mdcwhen 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.mdand keep Cursor-specific, file-scoped rules in.cursor/rules.
The three options at a glance
-
Project rules:
.mdcfiles 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.
Rule files
.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. -
globsset andalwaysApply: false: attached automatically when a matching file is in context (Apply to Specific Files). -
descriptionset, 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:
.cursor/rules/components.mdc
---
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:
.cursor/rules/services.mdc
---
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
# 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.
Nested AGENTS.md
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.mdtoo, but only when your project has noCLAUDE.md(orCLAUDE.local.md) in the working directory or above it, and it needs Claude Code v2.1.277 or later. If you have both, it readsCLAUDE.mdonly, unless you change the Project instructions setting in the Claude Code configuration screen. -
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
- Create a new rule: open the command palette and run New Cursor Rule (or use
/create-rule). - Copy the contents of
.cursorrulesinto the new rule. - Set the rule type to Always Apply, which matches the old behaviour.
- Delete
.cursorrulesfrom 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.mdis faster to write; a single always-apply rule is equivalent. -
Team uses Cursor plus Claude Code, Codex or another agent:
AGENTS.mdfor the shared facts, so nobody maintains duplicate files. -
Different conventions for different file types (React components versus SQL migrations):
.cursor/ruleswith globs.AGENTS.mdhas 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:
CLAUDE.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.
If you want ready-made Cursor project rules instead of writing them from scratch, the (paid) Next.js + Tailwind Rules Pack for Cursor has 8 .mdc files for Next.js App Router, Server Components, Tailwind, TypeScript and testing. You don't need it to follow this guide.
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.
Sources
Commands and config above come from these official docs. Tools change often, so check them for the latest steps.
- Cursor docs: Rules
- Cursor help: Rules (including migrating from .cursorrules)
- Cursor forum: .cursorrules is legacy, use .cursor/rules (staff reply, March 2026)
- agents.md: the AGENTS.md format, FAQ and supported tools
- agentsmd/agents.md on GitHub
- Claude Code docs: How Claude remembers your project (CLAUDE.md and AGENTS.md)
Tools in this guide
PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email pluginstackai@gmail.com.
This guide was first published on PluginStack. Browse the PluginStack directory for more hand-checked MCP servers, plugins and setup guides.
Top comments (0)