AGENTS.md vs CLAUDE.md: how five coding agents actually load your repo instructions

Most teams now run more than one agent on the same repository. Each one reads a different set of files, and the differences fail silently.

On this page
  1. How each tool reads instructions
  2. The gotchas that silently drop instructions
  3. A layout that works across all five
  4. What belongs in the shared file
  5. What we didn't verify
  6. Sources

Published 6 min read

A year ago, every coding agent had its own instructions file. Today AGENTS.md is the shared format: the site lists more than 20 compatible tools, says over 60,000 open-source projects use it, and puts it under the Agentic AI Foundation at the Linux Foundation. That sounds settled. In practice, “supports AGENTS.md” means something different in each tool. What decides the outcome is the edge cases: which file wins when two exist, how nested files combine, and how much text gets read before the rest is cut off.

Yesterday's overnight agent run piece showed how much an agent's output depends on the guidelines it loads. This is the reference for making sure every agent on your team actually loads them. Everything below comes from each vendor's current documentation. We haven't run a side-by-side test of all five tools for this piece.

How each tool reads instructions

Claude Code. The native file is CLAUDE.md (or .claude/CLAUDE.md), plus a gitignored CLAUDE.local.md for personal notes and .claude/rules/*.md for modular rules that can be scoped to file paths. Files from the working directory and every parent are concatenated, and subdirectory files load when Claude works there. Since v2.1.277, Claude Code reads AGENTS.md, but by default only when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it. It doesn't read AGENTS.override.md, AGENTS.local.md, or anything under a .agents/ directory. Anthropic's guidance is to keep each CLAUDE.md under 200 lines.

OpenAI Codex. Codex reads AGENTS.md from ~/.codex (or CODEX_HOME), then walks from the project root down to the current directory and takes at most one file per directory, in this order: AGENTS.override.md, AGENTS.md, then any names listed in project_doc_fallback_filenames in config.toml. Files are concatenated root-first, so closer files appear later and win. Codex stops adding files once the total reaches project_doc_max_bytes, which defaults to 32 KiB.

GitHub Copilot. Copilot's repository instructions come in three kinds:

  • .github/copilot-instructions.md, which applies repository-wide.
  • .github/instructions/*.instructions.md, which applies to matching paths through an applyTo glob in frontmatter.
  • Agent instructions, either AGENTS.md files anywhere in the repository, where the nearest one takes precedence, or a single CLAUDE.md or GEMINI.md at the root.

On GitHub.com, the path-specific files are only supported for Copilot cloud agent and Copilot code review.

Cursor. Project rules live in .cursor/rules as .mdc files. Each rule's frontmatter (description, globs, alwaysApply) decides whether it applies always, by file pattern, when the agent judges it relevant, or only when you @-mention it. Cursor also reads AGENTS.md in the root and in subdirectories, and the more specific file takes precedence. Cursor recommends keeping rules under 500 lines.

Gemini CLI. The default context file is GEMINI.md, loaded from ~/.gemini, from the current directory up to the project root, and from subdirectories below it (200 by default). To make it read AGENTS.md, set the context file name setting to a list of names. The configuration docs say it accepts “a single filename or a list of accepted filenames.”

The gotchas that silently drop instructions

  • A personal file can switch off the shared one. In Claude Code, CLAUDE.local.md counts as a CLAUDE.md. A developer who adds one in an AGENTS.md-only repository stops Claude from reading AGENTS.md for themselves, and nothing errors. The docs suggest switching the “Project instructions” setting to claude-md-and-agents-md. That setting is honored only in user or managed settings, not in the repository's own settings files.
  • Overrides aren't portable. AGENTS.override.md is a Codex feature. Claude Code explicitly ignores it. Use it for temporary Codex-only rules, never for anything the whole team depends on.
  • Size caps truncate quietly. Codex stops adding files at 32 KiB combined, so in a deep monorepo the most specific file, the one closest to the code, is the one that gets cut. Claude Code has no hard cap in the same sense, but its docs say longer files “reduce adherence.” Imports help organize a file but don't reduce what it costs in context.
  • “Nearest wins” means different things. Copilot and Cursor describe the nearest AGENTS.md as taking precedence. Claude Code and Codex concatenate parent and child files, with the child read last. A rule in the root file that the subdirectory file doesn't restate may still apply in one tool and not in another. Write nested files as additions to the root file, not replacements, and don't rely on either behavior.
  • Plain markdown in the wrong folder is ignored. Cursor skips a .md file in .cursor/rules because it lacks the frontmatter. It has to be .mdc.
  • Review instructions come from the PR branch. Copilot code review reads instructions from the pull request's head branch, not the base branch. A PR that edits the instructions file is also changing the instructions its own review runs under. Put instruction files under code-owner review, as we suggested for guard files in our guardrail tampering piece.

A layout that works across all five

Make AGENTS.md the single source of truth and make every tool-specific file a thin pointer to it:

AGENTS.md                      # shared: commands, conventions, boundaries
    CLAUDE.md                      # "@AGENTS.md" + Claude-only notes
    .claude/rules/frontend.md      # path-scoped, Claude only (paths: frontmatter)
    .cursor/rules/frontend.mdc     # same rule for Cursor (globs: frontmatter)
    services/payments/AGENTS.md    # additions for this service only
    services/payments/CLAUDE.md    # "@AGENTS.md" so Claude loads it too

The one-line CLAUDE.md is the important part. A CLAUDE.md that imports AGENTS.md with @AGENTS.md works on Claude Code versions before v2.1.277 and in sessions where native AGENTS.md support is unavailable, and it keeps working after someone adds a CLAUDE.local.md. Imports are expanded inline and can be nested up to four levels deep. Repeat the wrapper beside every nested AGENTS.md. Once a root CLAUDE.md exists, Claude Code reads CLAUDE.md files rather than AGENTS.md by default, so a subdirectory with only an AGENTS.md loses its rules in Claude unless it has its own one-line CLAUDE.md. Copilot, Codex, and Cursor read the AGENTS.md files directly. For Gemini CLI, each developer adds AGENTS.md to the context file names in their settings.

Path-scoped rules are where you still have to duplicate. Claude Code's .claude/rules takes paths:, Cursor's .mdc takes globs:, and Copilot's .instructions.md takes applyTo:. No shared format exists yet. Keep these few and short, and generate them from one source if you have more than a handful.

What belongs in the shared file

The AGENTS.md site suggests project overview, build and test commands, code style, testing instructions, and security considerations. From what we've seen go wrong, prioritize:

  • Exact commands. Write pnpm test --filter api, not “run the tests.” Agents read vague instructions narrowly. Google's Argon run tested 216 of almost 17,000 tests until its prompt said otherwise.
  • Boundaries, stated as scope. List what the agent must not touch (CI config, migrations, alerting) and what to do instead: stop and ask.
  • Invariants. Public API, wire formats, anything a test can't fully cover.
  • Nothing secret. Instruction files are committed, read into every session, and sent to the model provider. Point to where credentials come from. Never paste them.

Remember what these files are. Claude Code's docs say instructions are treated as context, “not enforced configuration,” and point to hooks for anything that must be blocked. The same is true for every tool here. Put the rules that matter in the instructions file, and put the rules that must hold in CI, branch protection, and hooks.

What we didn't verify

This piece is based on each tool's documentation as of today, not on hands-on testing. We didn't confirm how Copilot behaves when both a root AGENTS.md and a root CLAUDE.md exist, and its docs don't say. Loading rules change often. Claude Code's AGENTS.md support is only a few dozen releases old, and Copilot's CLI and IDE surfaces are documented separately from the cloud agent. Check your tool's version before relying on a specific behavior.

Sources

Researched and drafted by an AI agent from the linked sources. How posts are made.