Reference · Coding Agent Rules

CLAUDE.md vs. AGENTS.md vs. .cursorrules: file locations, limits, and shared setup.

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.

Quick answer: Use AGENTS.md for cross-tool repo rules (Codex CLI and compatible agents; 32 KiB default cap), CLAUDE.md and .claude/rules/*.md for Claude Code, .cursor/rules/*.mdc for Cursor, .github/copilot-instructions.md for GitHub Copilot, and GEMINI.md for Gemini Code Assist. Keep repo build rules in one file and store personal communication style in user-global configs.
On this page

Complete repository rules matrix across 5 coding agents.

Coding agentPrimary repo file(s)User / global scopeSize / load notesDeep-dive guide
Claude CodeCLAUDE.md, CLAUDE.local.md, .claude/rules/*.md~/.claude/CLAUDE.mdSupports modular @path imports; nested dir loading on readCLAUDE.md examples →
OpenAI Codex CLIAGENTS.md, AGENTS.override.md~/.codex/AGENTS.md (~/.codex/config.toml)Default project_doc_max_bytes = 32 KiB combinedAGENTS.md guide →
Cursor.cursor/rules/*.mdc (legacy .cursorrules)Cursor Rules for AI user settingsSupports Always, Auto-Attached globs, Agent Requested descriptionsCursor/Copilot/Gemini →
GitHub Copilot.github/copilot-instructions.md & .github/instructions/*.instructions.mdIDE user instructionsPath-scoped frontmatter via applyTo globsCursor/Copilot/Gemini →
Gemini Code Assist / CLIGEMINI.md (project root & subdirs)~/.gemini/GEMINI.mdHierarchical context loading along working treeCursor/Copilot/Gemini →

How to keep one single source of truth across tools without drift.

Two simple habits prevent conflicting rules across coding agents:

  1. Keep shared repo rules in AGENTS.md: Put build commands, test runners, protected directories, and commit rules in AGENTS.md. Keep CLAUDE.md short with an @AGENTS.md import plus any Claude-specific notes.
  2. 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 gitignored CLAUDE.local.md.

Starter communication block for personal global coding-agent files (~360 characters):

## Personal Engineering Communication Style - Give root cause, exact file paths, and minimal diff or command first. - Keep prose under 4 sentences unless I ask for architectural walkthroughs. - Never extrapolate test outputs or claim checks passed unless executed after the final edit. - Ask before refactoring unrelated files or changing public APIs.

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.

Sources.

Keep going.