Agent Friendly Code

Cursor rules vs AGENTS.md: which should you use?

Use AGENTS.md for what every agent should know, and add .cursor/rules/*.mdc only for rules that apply to some files or tasks. Cursor reads both, and a root CLAUDE.md too. A .cursorrules file is legacy and will be deprecated.

How do they differ?

Where
Cursor rules: .cursor/rules/*.mdc, in folders if you like. A plain .md there is ignored.
AGENTS.md: The repo root, and any subdirectory.
Format
Cursor rules: Markdown with description, globs and alwaysApply frontmatter.
AGENTS.md: Plain markdown, no metadata.
When Cursor applies it
Cursor rules: Always, for matching files, when the agent judges the description relevant, or on @-mention.
AGENTS.md: Always. A nested one applies to work in its directory, more specific winning.
Repos with one
Cursor rules: 20 of 401 (5%)
AGENTS.md: 203 of 401 (51%)
Agents that read it
Cursor rules: 2 of 9: Cursor and Devin
AGENTS.md: 6 of 9; which ones

18 of the 20 repos with Cursor rules also have an AGENTS.md or CLAUDE.md. Empty files don't count.

How do I use both?

  1. Put the project, commands and rules every agent needs in AGENTS.md.
  2. Add one .mdc rule per topic that only some files need, scoped with globs.
  3. Move .cursorrules into a rule set to Always Apply, which matches its old behaviour, then delete it.

What does it look like?

Cursor · .cursor/rules/api.mdc

---
description: Conventions for API route handlers
globs: app/api/**/*.ts
alwaysApply: false
---

- Return errors as JSON with a status code; never throw to the framework.

From the docs: cursor.com/context/rules · cursor.com/customization/rules · cursor.com/using

How we score Cursor rules · AGENTS.md vs CLAUDE.md · Make a repo agent-ready