CLAUDE.md vs AGENTS.md: How Cursor Reads Them

When CLAUDE.md and AGENTS.md sit in the same repo, the question is how Cursor Agent (Chat) picks them up. This post covers read and apply behavior only, from the official Rules and Rules help docs. No pricing.

An earlier AGENTS.md / CLAUDE.md post was about using and syncing the files across tools. This one is about what Cursor always injects, and where conditional norms belong.

How does Cursor read both?

One-line answer: Cursor auto-reads root AGENTS.md and CLAUDE.md. CLAUDE.md is always applied to every conversation; AGENTS.md is plain-markdown guidance at the root and in nested folders.

File	Role in Cursor	When it applies
`AGENTS.md`	Plain-markdown alternative to `.cursor/rules` (no metadata)	Root and subdirs; nested files combine when you work in that tree; more specific path wins
`CLAUDE.md`	Read for Claude Code compatibility	Always every chat—ignores any `alwaysApply` frontmatter
`.cursor/rules/*.mdc`	Project Rules (can be conditional)	Always / globs / Intelligent / manual `@`
`.cursorrules`	Legacy	Migrate to an Always Apply `.mdc`, then delete

The help page How does CLAUDE.md work in Cursor? is explicit: Cursor picks up CLAUDE.md like AGENTS.md, but application is unconditionally always. Claude-only workflows written there (“always run pnpm test before commit”) leak into Cursor sessions.

AGENTS.md has no frontmatter. Split by path with nested AGENTS.md, or move conditional norms into .mdc files.

project/
  AGENTS.md                 # shared baseline
  CLAUDE.md                 # always on in Cursor — keep short & shared
  frontend/
    AGENTS.md               # merges when working under frontend/
  .cursor/rules/
    api-routes.mdc          # conditional via globs

How do always-apply and conditional rules differ?

One-line answer: CLAUDE.md (and plain AGENTS.md) behave like always-on context; to choose when text is injected, use .cursor/rules/*.mdc with alwaysApply, globs, and description.

Four Project Rule types (official Rules docs):

Type	Frontmatter signal	Behavior
Always Apply	`alwaysApply: true`	Every chat (globs/description ignored)
Apply to Specific Files	`alwaysApply: false` + `globs`	Attach when matching files are in context
Apply Intelligently	`alwaysApply: false` + `description`	Agent pulls in when relevant
Apply Manually	neither	Only via `@rule`

Practical split:

Short, every session — reply language, secrets ban, never-edit generated dirs → short Always .mdc or thin AGENTS.md / thin shared CLAUDE.md.
Path-scoped — schemas under src/api/** → globs Rule. CLAUDE.md cannot be conditional via frontmatter.
Occasional — Intelligent (description) or manual @.
A plain .md under .cursor/rules is ignored. Use .mdc, or put plain markdown in AGENTS.md.

---
globs: src/routes/api/**/*.ts
alwaysApply: false
---

- Validate inputs at the route boundary.
- Return the existing typed error shape.

Team/Enterprise Team Rules are dashboard free-form text (optional globs). On conflict, official order is Team → Project → User. No plan limits or prices here.

Where should a mixed team put what?

One-line answer: Put shared facts and coding norms in AGENTS.md, Cursor-only path scopes in .cursor/rules/*.mdc, and Claude-shared lines in a thin CLAUDE.md (or @AGENTS.md bridge)—keep Claude-only procedures out of CLAUDE.md so they do not always hit Cursor.

Situation	Put it in	Why
Cursor + Claude Code	`AGENTS.md` = shared base; thin `CLAUDE.md` bridge/shared only	Cursor always reads `CLAUDE.md` → Claude-only long procedures leak
Cursor-heavy, path norms	Shared `AGENTS.md` + `.mdc` globs	Conditionals live only in `.mdc`
Monorepo areas	Nested `AGENTS.md`	Merges for that tree; closer path wins
Org-wide force	Team Rules (dashboard)	Precedence over Project/User; Enforce is a team setting
Old `.cursorrules`	Always Apply `.mdc`, then delete	Official: legacy, to be deprecated

Checklist:

Question	Yes →	No →
Must Claude Code and Cursor both follow it?	Thin shared in `AGENTS.md` (+ `CLAUDE.md` bridge if needed)	Keep Claude-only off Cursor’s always-on file
Must it apply only for paths/types?	`.cursor/rules` + `globs`	Plain `AGENTS.md` / Always
Short and every chat?	Always `.mdc` or short root md	Intelligent / `@` / Skill

Closing

CLAUDE.md vs AGENTS.md in Cursor is about read and apply. Cursor auto-reads both; CLAUDE.md is always on. Put conditionals in .mdc (alwaysApply / globs / description), and keep the team baseline in AGENTS.md. See Rules and Rules help.

Sources

Cursor Rules — Project Rules, nested AGENTS.md, Team Rules precedence
Rules help — CLAUDE.md always-apply, .cursorrules migration