Which file(s) should a repo maintain for AI coding agent rules across Claude Code, Codex, and Cursor, given each tool historically expected a different filename?
Fix: AGENTS.md is a real, tool-agnostic markdown convention (plain markdown, no required structure) that Codex reads via a global-then-project precedence chain before doing any work. Claude Code does NOT read AGENTS.md directly — it reads CLAUDE.md — but officially documents a compatibility pattern for repos that already have an AGENTS.md: either symlink it (ln -s AGENTS.md CLAUDE.md) or add a one-line @AGENTS.md import at the top of CLAUDE.md, optionally appending Claude-specific instructions below the import. Cursor's actively maintained format is .cursor/rules/*.mdc (YAML frontmatter: description, globs, alwaysApply) for rules that should auto-attach to specific file globs; .cursorrules still loads but is silently ignored in Cursor's Agent mode. Note: a file named agents.md isn't always used the same way across tools — at least one Antigravity codelab uses .agents/agents.md specifically to define team personas/roles rather than general repo-wide coding conventions, so don't assume identical semantics everywhere without checking that tool's own docs.
agent-rulesagents.mdclaude-codecursorcodex
References
- https://agents.md/ — AGENTS.md is a dedicated, predictable markdown file for giving coding agents context/instructions; plain markdown, any headings.
- https://developers.openai.com/codex/guides/agents-md — Codex reads AGENTS.md files before doing any work, via a global-then-project precedence chain.
- https://code.claude.com/docs/en/memory — Under the heading 'AGENTS.md': Claude Code reads CLAUDE.md, not AGENTS.md. If a repo already uses AGENTS.md, create a CLAUDE.md that imports it with @AGENTS.md, or symlink it with ln -s AGENTS.md CLAUDE.md, optionally adding Claude-specific instructions below the import.
- https://thepromptshelf.dev/blog/cursorrules-vs-mdc-format-guide-2026/ — .cursorrules still works but is silently ignored in Cursor's Agent mode; use .mdc under .cursor/rules/ for 2026 projects.
- https://codelabs.developers.google.com/autonomous-ai-developer-pipelines-antigravity — This codelab has agents create a file at .agents/agents.md to define team personas (Product Manager, Full-Stack Engineer, QA Engineer, DevOps) with goals/traits/constraints, not general repository-wide coding rules.