Cursor Rules vs AGENTS.md vs CLAUDE.md (2026)

Cursor's native format is .cursor/rules/*.mdc, Claude Code's is CLAUDE.md, and AGENTS.md is the tool-neutral markdown file several agents read. If you use more than one agent, keep one short source of truth and generate the others from it with the Config Converter instead of hand-copying.

Verdict

One agent: use that agent's native file. Cursor plus Claude Code: write the shared conventions once (AGENTS.md is the neutral choice), then generate .cursor/rules/*.mdc and CLAUDE.md from it. Hand-maintained copies drift, and a rule that exists in only one of two files means one agent quietly ignores it.

Compatibility matrix

AgentNative file
Cursor.cursor/rules/*.mdc (legacy .cursorrules)
Claude CodeCLAUDE.md
CodexAGENTS.md
Windsurf.windsurf/rules

These are the conventions we see in the wild. Tools change fast, so confirm exact filenames and fallbacks in each vendor's current docs before you delete a file.

What each format can express

  • .mdc carries frontmatter (description, globs, always-apply), so a rule can fire only on app/api/**. That scoping is Cursor-specific.
  • CLAUDE.md is plain markdown loaded as project memory. No glob frontmatter, so scope in prose or split into several files.
  • AGENTS.md is plain markdown with no required schema. Maximum portability, no scoping.

Conversion is lossy in one direction: .mdc to markdown drops the globs, and markdown to .mdc has to guess them. Review the output for any rule that depended on a path.

Precedence and loading behaviour

Don't rely on precedence to resolve conflicts. If two files disagree, different agents may pick different winners, and you won't notice until a review. Keep each instruction in exactly one source file, and keep the always-loaded text short, because everything loaded costs tokens on every turn.

Practical split: always-on bans (tenant from session, no any) go in the shared file; longer manuals go in skills that load on demand. See Rules vs Skills vs Commands.

One source, many agents: how to convert

  1. Pick the source. For a mixed-agent setup, AGENTS.md.
  2. Trim it. Grade it with the Rules File Grader and cut anything the agent can learn by reading your code.
  3. Drop it into the Config Converter and pick .mdc or CLAUDE.md as the target.
  4. Add globs back by hand to any Cursor rule that should be path-scoped.
  5. Commit the source and the generated files, and re-convert whenever the source changes.

When not to convert

If you only use Cursor, keep native .mdc rules and their globs. Flattening to a lowest-common-denominator file just to be tidy gives up scoping for nothing.

Related pages

Frequently asked questions

  • Does Cursor read AGENTS.md or CLAUDE.md?
    Cursor's native format is .cursor/rules/*.mdc. Support for other filenames has changed over time, so check Cursor's current docs; converting to .mdc is the safe route.
  • Should I keep both CLAUDE.md and AGENTS.md?
    Only if you use both Claude Code and an AGENTS.md agent. Keep one as the source and generate the other so they never diverge.
  • Is .cursorrules deprecated?
    The single-file .cursorrules is the legacy format; new projects should use .cursor/rules/*.mdc. The Config Converter accepts it as input.
  • Does converting lose information?
    Going from .mdc to plain markdown drops glob scoping and always-apply flags. Re-add them by hand when converting back.

Convert once, stop copy-pasting

Drop your rules file into the Config Converter, pick the target format, and download it.