{"slug": "cursor-rules-vs-agents-md-which-to-use-and-cursorrules", "title": "Cursor rules vs AGENTS.md: which to use (and .cursorrules)", "summary": "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.", "body_md": "Checked against the official docs: Oct 27, 2026\n\nCursor 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.\n\n`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.\nCursor 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.\n\nProject 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.\n\n*Rule files*\n\n```\n.cursor/rules/\n  react-patterns.mdc      # recognized\n  api-guidelines.md       # ignored (wrong extension)\n  frontend/\n    components.mdc        # recognized\n```\n\nThree frontmatter fields decide when a rule is included:\n\n`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:\n\n*.cursor/rules/components.mdc*\n\n```\n---\nglobs: src/components/**/*.tsx\nalwaysApply: false\n---\n\n- Use named exports, not default exports\n- Co-locate styles in a module CSS file next to the component\n- Keep components under 200 lines\n```\n\nA 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:\n\n*.cursor/rules/services.mdc*\n\n```\n---\ndescription: RPC service conventions and patterns for the backend\nalwaysApply: false\n---\n\n- Define each service in its own file under `src/services/`\n- Validate inputs at the service boundary\n- Read `@service-template.ts` before creating a new service\n```\n\nCreate 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.\n\n[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:\n\n```\n# AGENTS.md\n\n## Setup commands\n- Install deps: `pnpm install`\n- Start dev server: `pnpm dev`\n- Run tests: `pnpm test`\n\n## Code style\n- TypeScript strict mode\n- Single quotes, no semicolons\n```\n\nCursor 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.\n\n*Nested AGENTS.md*\n\n```\nproject/\n  AGENTS.md              # global instructions\n  frontend/\n    AGENTS.md            # frontend-specific\n  backend/\n    AGENTS.md            # backend-specific\n```\n\nThe 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:\n\n`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.\n\nPer agents.md, the closest `AGENTS.md` to the file being edited wins, and explicit instructions you type in chat override everything.\n\nThe `.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.\n\n`/create-rule`).\nIf the instructions aren't Cursor-specific, you could put them in `AGENTS.md` instead and skip the rule file.\n\nCursor 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`:\n\n```\n@AGENTS.md\n\n## Claude Code\n\nUse plan mode for changes under `src/billing/`.\n```\n\nA 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.\n\nCursor'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.\n\nIf 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.\n\nYes. Cursor supports `AGENTS.md` in the project root and in subdirectories.\n\nOnly if you don't need scoping. Rules can attach by glob, by description or by @-mention; `AGENTS.md` is always plain instructions.\n\nNo. 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`.\n\nCheck 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.\n\nNo. Cursor says rules don't impact Cursor Tab or other AI features.\n\nMCP 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/).\n\nCommands and config above come from these official docs. Tools change often, so check them for the latest steps.\n\nPluginStack 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).\n\nThis 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.", "url": "https://wpnews.pro/news/cursor-rules-vs-agents-md-which-to-use-and-cursorrules", "canonical_source": "https://dev.to/pluginstackai/cursor-rules-vs-agentsmd-which-to-use-and-cursorrules-33ci", "published_at": "2026-11-20 19:07:25+00:00", "updated_at": "2026-11-20 19:14:05.307305+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["Cursor", "Agentic AI Foundation", "Linux Foundation", "GitHub Copilot", "Codex", "Gemini CLI", "Windsurf"], "also_reported_by": [], "takeaway": "Cursor ignores plain .md files in .cursor/rules, so name rule files .mdc with frontmatter setting alwaysApply, globs or description, and keep each rule under 500 lines while pointing to example files instead of copying code.", "recommendation": {"advice": "Put project rules in .cursor/rules as .mdc files with frontmatter (alwaysApply, globs or description) and use nested AGENTS.md for simple cases, adding a rule only after the agent repeats the same mistake.", "playbook": "coding-agents", "playbook_url": "https://wpnews.pro/playbooks/coding-agents"}, "alternates": {"html": "https://wpnews.pro/news/cursor-rules-vs-agents-md-which-to-use-and-cursorrules", "markdown": "https://wpnews.pro/news/cursor-rules-vs-agents-md-which-to-use-and-cursorrules.md", "text": "https://wpnews.pro/news/cursor-rules-vs-agents-md-which-to-use-and-cursorrules.txt", "jsonld": "https://wpnews.pro/news/cursor-rules-vs-agents-md-which-to-use-and-cursorrules.jsonld"}}