CLAUDE.md vs. AGENTS.md vs. .cursorrules: file locations, limits, and shared setup.
By Bernard Huang · Updated
A side-by-side matrix of every major coding agent instruction file so your repo never drifts across Claude Code, Codex, Cursor, Copilot, and Gemini CLI.
On this page
Complete repository rules matrix across 5 coding agents.
| Coding agent | Primary repo file(s) | User / global scope | Size / load notes | Deep-dive guide |
|---|---|---|---|---|
| Claude Code | CLAUDE.md, CLAUDE.local.md, .claude/rules/*.md | ~/.claude/CLAUDE.md | Supports modular @path imports; nested dir loading on read | CLAUDE.md examples → |
| OpenAI Codex CLI | AGENTS.md, AGENTS.override.md | ~/.codex/AGENTS.md (~/.codex/config.toml) | Default project_doc_max_bytes = 32 KiB combined | AGENTS.md guide → |
| Cursor | .cursor/rules/*.mdc (legacy .cursorrules) | Cursor Rules for AI user settings | Supports Always, Auto-Attached globs, Agent Requested descriptions | Cursor/Copilot/Gemini → |
| GitHub Copilot | .github/copilot-instructions.md & .github/instructions/*.instructions.md | IDE user instructions | Path-scoped frontmatter via applyTo globs | Cursor/Copilot/Gemini → |
| Gemini Code Assist / CLI | GEMINI.md (project root & subdirs) | ~/.gemini/GEMINI.md | Hierarchical context loading along working tree | Cursor/Copilot/Gemini → |
How to keep one single source of truth across tools without drift.
Two simple habits prevent conflicting rules across coding agents:
- Keep shared repo rules in
AGENTS.md: Put build commands, test runners, protected directories, and commit rules inAGENTS.md. KeepCLAUDE.mdshort with an@AGENTS.mdimport plus any Claude-specific notes. - Keep personal tone in user-global files: Do not commit personal verbosity or tone preferences to the team repo. Save personal style in
~/.claude/CLAUDE.md,~/.codex/AGENTS.md, or a gitignoredCLAUDE.local.md.
Starter communication block for personal global coding-agent files (~360 characters):
Why oversized rules files silently drop instructions.
OpenAI Codex CLI stops reading AGENTS.md files once the combined chain hits project_doc_max_bytes (32 KiB default in ~/.codex/config.toml; see our GPT-6 Astra guide). Across all coding agents, giant root instruction files drown out critical build and test commands. Keep root files under 100–250 lines, move file-specific rules into glob files (.cursor/rules/*.mdc, .claude/rules/*.md, *.instructions.md), and merge personal rules safely with our Instruction Converter & Merger.
Questions people ask.
Does Cursor read AGENTS.md or only .cursor/rules?
Cursor natively uses .cursor/rules/*.mdc (and legacy .cursorrules) for project rules alongside AGENTS.md compatibility in newer agent workflows. Keeping AGENTS.md canonical and referencing or syncing concise Cursor rules prevents drift.
Should personal personality instructions be committed into repo AGENTS.md?
Keep repo-committed AGENTS.md and CLAUDE.md focused on build commands, code style, security constraints, and tests. Place personal communication preferences in global user files (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md) or gitignored CLAUDE.local.md.
What happens if AGENTS.md exceeds 32 KiB in Codex CLI?
Codex CLI stops loading additional AGENTS.md bytes past project_doc_max_bytes (default 32 KiB), which can silently cut off nested directory rules unless split cleanly or raised intentionally in ~/.codex/config.toml.
How do I merge my AgentTune style into an existing CLAUDE.md without deleting repo commands?
Use the AgentTune Instruction Converter & Merger: it wraps your communication preferences in labeled HTML comment markers and preserves every existing line outside those markers.
What changed.
- First published with side-by-side matrix covering CLAUDE.md, AGENTS.md, .cursorrules/.mdc, copilot-instructions.md, and GEMINI.md.