Cursor rules vs AGENTS.md: which to use (and .cursorrules) A developer guide compares Cursor's three mechanisms for giving coding agents standing instructions: project rules in .cursor/rules (.mdc files with YAML frontmatter controlling alwaysApply, globs and description), the open AGENTS.md format stewarded by the Agentic AI Foundation under the Linux Foundation, and the legacy .cursorrules file. It notes that plain .md files in .cursor/rules are ignored, that nested AGENTS.md files merge with parents and the more specific one wins, and that Cursor applies Team Rules before Project Rules before User Rules when guidance conflicts. 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. AGENTS.md .cursor/rules/ .mdc .cursorrules . .cursor/rules . .mdc files in .cursor/rules/ . Cursor-only. YAML frontmatter controls when each rule loads. Supports folders and globs. 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. 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. globs set and alwaysApply: false : attached automatically when a matching file is in context description set, no globs, 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 https://www.pluginstackai.com/plugins/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 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 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.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 See Codex CLI https://www.pluginstackai.com/plugins/codex-cli/ , OpenCode https://www.pluginstackai.com/plugins/opencode/ and Claude Code https://www.pluginstackai.com/plugins/claude-code/ for those tools. Per agents.md, the closest AGENTS.md to the file being edited wins, and explicit instructions you type in chat override everything. 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. /create-rule . If the instructions aren't Cursor-specific, you could put them in AGENTS.md instead and skip the rule file. 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. 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 https://www.pluginstackai.com/packs/ has 8 .mdc files for Next.js App Router, Server Components, Tailwind, TypeScript and testing. You don't need it to follow this guide. Yes. Cursor supports AGENTS.md in the project root and in subdirectories. Only if you don't need scoping. Rules can attach by glob, by description or by @-mention; AGENTS.md is always plain instructions. 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 . 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. No. Cursor says rules don't impact Cursor Tab or other AI features. MCP servers are configured separately in mcp.json . See how to add an MCP server to Cursor https://www.pluginstackai.com/guides/add-mcp-server-to-cursor/ . Commands and config above come from these official docs. Tools change often, so check them for the latest steps. PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email pluginstackai@gmail.com mailto:pluginstackai@gmail.com . This guide was first published on PluginStack https://www.pluginstackai.com/guides/cursor-rules-vs-agents-md/ . Browse the PluginStack directory https://www.pluginstackai.com/ for more hand-checked MCP servers, plugins and setup guides.