Is .cursorrules deprecated?

The single-file `.cursorrules` at repo root is legacy — Cursor still reads it for backward compatibility, but the modern format is a folder of `.cursor/rules/*.mdc` files, each with frontmatter (description, globs, alwaysApply) that controls when the rule loads. If you're starting fresh, use the `.cursor/rules/` folder, not a monolithic `.cursorrules`. The old file still works, but new Cursor features target the folder format.

Does Cursor read AGENTS.md?

Yes, Cursor added native AGENTS.md support in 2025-08. So a Cursor user can rely on AGENTS.md for the shared, tool-agnostic rules and add `.cursor/rules/*.mdc` only for Cursor-specific behavior (glob auto-attach, alwaysApply). You don't have to choose one — the recommended pattern is AGENTS.md as the source of truth plus thin Cursor rules for the features only Cursor has.

Which tools read AGENTS.md?

AGENTS.md emerged as a cross-tool standard read by Cursor, Codex CLI, Gemini CLI, Aider, Windsurf, Zed, Warp, RooCode, and others. The notable holdout is Claude Code, which doesn't read AGENTS.md natively as of May 2026 — the common workaround is a symlink (`ln -s AGENTS.md CLAUDE.md`). The whole point of AGENTS.md is that one file configures many tools, so a multi-tool team writes it once.

What can .cursorrules do that AGENTS.md can't?

Scoping. Cursor's `.mdc` frontmatter lets a rule auto-attach only when files matching a glob are in context (e.g., apply the React rules only when editing `.tsx`), mark a rule alwaysApply, or attach by description match. AGENTS.md is a flat document with no native per-file targeting — it's all loaded as general context. If you need 'these rules only when working on the API layer,' that's a Cursor `.mdc` feature, not an AGENTS.md one.

Should I keep both files in my repo?

For a multi-tool team, yes: AGENTS.md for the shared, tool-agnostic conventions (stack, what-not-to-do, where things live) and `.cursor/rules/*.mdc` for Cursor-specific scoping. Keep the Cursor rules thin — ideally pointers that say 'see AGENTS.md, and additionally for .tsx files do X.' Duplicating the same content into both files is the anti-pattern; they drift and contradict each other within a month.

Does AGENTS.md replace CLAUDE.md?

Not directly, because Claude Code doesn't read AGENTS.md natively yet. The bridge is a symlink (`ln -s AGENTS.md CLAUDE.md`), documented in Claude Code's issue tracker, so one file serves both. If you maintain a separate CLAUDE.md, keep it minimal and let AGENTS.md hold the shared truth — otherwise you're maintaining two sources that drift. See /topic/claude-md for the Claude-specific guidance.

AGENTS.md vs .cursorrules (May 2026): The Portable Standard vs the Cursor-Specific File

# AGENTS.md vs .cursorrules: Portable Standard vs Cursor-Specific File (May 2026) If you write rules for AI coding tools, you hit this fork: do you put your conventions in AGENTS.md — the cross-tool standard that Cursor, Codex CLI, Gemini CLI, Aider, Windsurf, and others all read — or in .cursorrules (now properly .cursor/rules/.mdc), the Cursor-specific format with richer scoping controls? The honest answer in 2026 is "both, with discipline." But knowing which file does what is the difference between a clean setup and two contradictory configs that drift apart. This page picks winners by dimension.

Who wins at what

AGENTS.md wins on cross-tool portability, being a single source of truth, future-proofing across tools, and onboarding multi-tool teams. Cursor's .mdc rules win on per-file glob scoping, auto-attach by file pattern, Cursor-specific controls (alwaysApply, description match), and granular rule organization in the .cursor/rules/ folder. The modern setup uses AGENTS.md for the shared truth and thin Cursor rules for what only Cursor can do.
Where AGENTS.md wins
Cross-tool portability. One file, many tools. AGENTS.md is read by Cursor (since 2025-08), Codex CLI, Gemini CLI, Aider, Windsurf, Zed, Warp, RooCode, and more. Write your stack, conventions, and deny-rules once, and every compatible tool honors them. That's the entire value proposition, and .cursorrules simply can't match it — it's Cursor-only. Single source of truth. With AGENTS.md as the canonical config, you have one place to update when conventions change. No syncing the same rule into five tool-specific files. For a team where different developers use different tools, this is the difference between consistency and chaos. Future-proofing. New AI coding tools increasingly ship AGENTS.md support out of the box because it's the emerging standard. Betting on the portable file means new tools your team adopts next year likely already read your config. A Cursor-specific file only ever helps Cursor users. Clean multi-tool onboarding. A new developer who uses Aider, Codex, or Gemini CLI gets your conventions automatically from AGENTS.md without learning Cursor's .mdc frontmatter. The shared file lowers the onboarding cost for a heterogeneous team.
Where .cursorrules (.mdc) wins
Per-file glob scoping. Cursor's .mdc frontmatter lets a rule auto-attach only when files matching a glob are in context — apply the React conventions only when editing .tsx, the API rules only under app/api/. AGENTS.md is flat: it's all general context with no native targeting. For large repos where rules differ by area, this scoping is genuinely valuable. Auto-attach by pattern and alwaysApply. Beyond globs, Cursor rules can be marked alwaysApply or attached by description match, giving fine control over when each rule enters context. That conditional loading keeps the prompt focused — a level of control AGENTS.md doesn't offer. Granular organization. The .cursor/rules/ folder lets you split rules into many small, single-purpose .mdc files (one for testing, one for styling, one for the data layer) rather than one long document. For a big project, that modularity is easier to maintain than a monolithic file. Cursor-native features track here. New Cursor capabilities target the .mdc format. If you want the latest Cursor rule behavior, it lands in .cursor/rules/, not in the portable AGENTS.md.
Where the comparison gets uncomfortable
Duplication is the trap. The failure mode is copying the same conventions into both AGENTS.md and .cursor/rules/.mdc. Within a month they drift, contradict, and you can't tell which one Cursor actually obeyed. The discipline: AGENTS.md holds the shared truth, Cursor rules are thin — pointers plus the few genuinely Cursor-specific additions (globs, alwaysApply). Cursor's format keeps moving. The .cursorrules → .cursor/rules/.mdc migration left legacy files everywhere, and Cursor 2.0's glob auto-attach shipped with its own bugs (forum.cursor.com/t/140641). A project started in 2024 probably has rules that are wrong by 2026 conventions. AGENTS.md has been more stable as a flat document. Claude Code is the asterisk. AGENTS.md's "every tool reads it" pitch has one hole: Claude Code doesn't read it natively as of May 2026. The symlink workaround (ln -s AGENTS.md CLAUDE.md) closes the gap, but it's a workaround, and it's worth knowing before you assume universality.
The recommended setup
For a multi-tool team:
AGENTS.md at repo root — stack, conventions Claude/agents wouldn't guess, what-not-to-do, where things live. The shared source of truth.

.cursor/rules/.mdc* — only Cursor-specific additions: glob-scoped rules, alwaysApply flags. Keep them thin and reference AGENTS.md rather than duplicating it.

Symlink for Claude Code — ln -s AGENTS.md CLAUDE.md so Claude Code reads the same truth.
RuleSell's catalog ships rule packs authored as portable AGENTS.md content with optional Cursor .mdc wrappers — install once, use across tools, no duplication.
Where this comparison fails / what we don't know
We didn't run a controlled test of which file produces better agent behavior, because they're not really alternatives at the same layer — AGENTS.md is the portable base and Cursor rules are the scoping layer on top. The "winner" per dimension reflects what each format is for*, not a benchmark of output quality. We also don't know how long Claude Code stays an AGENTS.md holdout, or whether the standard's adoption stays as broad as it is today. Tool conventions in this space shift within release cycles. Treat the recommended setup as current best practice, not a permanent fixture.