Skip to content
vibespell

.cursorrules vs AGENTS.md

When to use a Cursor .cursorrules file, .cursor/rules, or a shared AGENTS.md, and how to keep them from drifting.

They are read by different tools

`.cursorrules` and `.cursor/rules/*.mdc` are Cursor files. AGENTS.md is the shared file that Cursor, Codex, and other agents read. If only Cursor edits the repo, a Cursor rule is enough. If more than one agent edits it, AGENTS.md is the file to maintain.

You can commit both. The failure mode is drift: Cursor is told to use server components while AGENTS.md still mentions the pages router. Generate both from the same options, then edit them together.

Which one wins inside Cursor

Cursor applies its own rule files with frontmatter and globs. AGENTS.md is additional project context. When they disagree, you will get inconsistent edits. Pick the Cursor rule as the always-on source for Cursor-only details, and keep AGENTS.md aligned on stack and commands.

Do it in this order

  1. 01

    List the agents that touch the repo

    Cursor only, or Cursor plus Codex, Copilot, or Claude Code.

  2. 02

    Choose the shared file

    Use AGENTS.md when more than one agent edits. Use Cursor rules when Cursor is the only one.

  3. 03

    Generate both if you need both

    Start from the same stack and strictness so the commands match.

  4. 04

    Delete the stale root file

    A leftover .cursorrules from a template will fight the new .mdc file.

Questions

Is .cursorrules deprecated?

Cursor's current format is `.cursor/rules/*.mdc`. A root `.cursorrules` file still appears in older projects. Do not keep two conflicting copies.

Should the files be identical?

The stack, commands, and bans should match. Cursor-specific frontmatter does not belong in AGENTS.md.

Related