The short version
| AGENTS.md | .cursorrules | |
|---|---|---|
| Read by | Cursor, Claude Code, Codex, Copilot, Gemini and more | Cursor |
| Scope | Tool-neutral, repo-wide convention | Cursor-specific |
| Location | AGENTS.md at repo root | .cursorrules at repo root |
| Best as | Your single source of truth | A view onto that source |
When to use which
If your team uses more than one agent — or might in future — keep your rules in AGENTS.md and treat .cursorrules as a generated copy. If you’re Cursor-only forever, a standalone .cursorrules is fine, but you give up portability the day someone opens the repo in Claude Code or Codex.
The trap: maintaining both
Teams often end up with a .cursorrules, a CLAUDE.md and a half-finished AGENTS.md that quietly disagree. The fix is one canonical file plus generated copies: keep AGENTS.md as the source and symlink or export the rest, so a change in one place updates all of them.
How to consolidate
The generator writes a single AGENTS.md and exports the same content as .cursorrules, CLAUDE.md and Copilot’s file — or gives you a one-line symlink script so every tool reads the same source.
Frequently asked
Does Cursor read AGENTS.md?
Cursor supports the AGENTS.md convention; you can also keep a .cursorrules that points at it. Either way, maintain one source and generate the other.
Can I have both files?
Yes, but symlink .cursorrules to AGENTS.md (or generate it) so they can’t drift apart.
Which should a new project use?
Start with AGENTS.md — it’s portable across tools — and add tool-specific files only as generated copies.