Three vendors published a size limit for their agent instruction files and no two of them agree. Anthropic targets under 200 lines per CLAUDE.md file. OpenAI’s Codex stops collecting instructions at 32 KiB by default. Cursor advises keeping rules under 500 lines. GitHub’s own prompt for generating copilot-instructions.md tells the agent the file must be no longer than two pages. That is a spread wide enough that a file which perfectly satisfies one tool is two and a half times over the recommendation of another.

Before that disagreement mattered, there was a filename disagreement, and that one got resolved. AGENTS.md is now the shared format, read by Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, Aider, Windsurf, Devin, Zed, Warp, VS Code, opencode, Semgrep’s coding agent, and a dozen others. Here is what each tool actually does with it.

The state of the format

ToolReads AGENTS.mdWhereDocumented size guidance
Anthropic Claude CodeYes, but only conditionallyWorking directory and every directory above it; subdirectories on demandTarget under 200 lines per file; files over 4 MiB are skipped entirely
OpenAI CodexYes~/.codex, then project root down to your working directoryproject_doc_max_bytes defaults to 32 KiB
CursorYes, root and subdirectoriesNested files combine with parentsKeep rules under 500 lines
GitHub CopilotYes, stored anywhere in the repoNearest AGENTS.md in the directory tree takes precedenceNo published limit; the generator prompt says no longer than 2 pages and not task specific

Worth reading the Anthropic row twice, because “yes, but only conditionally” is doing real work there, and the codex row is not a line count at all. Codex concatenates files from the project root downward and stops adding once the combined size reaches project_doc_max_bytes, 32 KiB by default. That is roughly 500 to 600 lines of plain text, which means Codex will happily read a file twice the size Anthropic tells you not to write. The knob is configurable, and the docs tell you to raise it or split across nested directories when you hit the cap.

Why the standard won

The AGENTS.md site gives the rationale plainly: README files are for humans, covering quick starts, project descriptions, and contribution guidelines, while AGENTS.md holds the extra context coding agents need, such as build steps, tests, and conventions that would clutter a README or are irrelevant to human contributors. The stated reason for not inventing another proprietary file is that they wanted a name and format that could work for anyone.

The scale is now part of the case: the format is used by over 60,000 open-source projects, and it is stewarded by the Agentic AI Foundation under the Linux Foundation. It is an actual published specification rather than an emerging convention, which is what happened to .cursorrules and .windsurfrules before it.

The scale detail that will convince you this is the long-term format is the main OpenAI repository, which contains 88 AGENTS.md files, one per package. That is the pattern the specification recommends for large monorepos, and it is already how one of the largest agent-friendly codebases is organised.

Four different answers to the same question

Every tool resolves instruction conflicts, and no two resolve them the same way. This is the part that will quietly produce different behaviour in the same repository.

ToolConflict resolution
AGENTS.md specificationThe closest file to the edited file wins; explicit user chat prompts override everything
CursorTeam Rules, then Project Rules, then User Rules, with earlier sources taking precedence
Cursor on nested AGENTS.mdMore specific instructions take precedence over parents
Anthropic Claude CodeAll files are concatenated, root first, so later files are read last; if two instructions contradict, Claude may pick one arbitrarily
GitHub CopilotPersonal instructions take highest priority, then repository, then organization; all relevant sets are provided

Anthropic’s row is the one to sit with. Its own documentation states that if a user rule and a project rule conflict, Claude may follow either one, and that you should keep the two consistent. That is not a bug description, it is a documented admission that the conflict resolution is the model’s discretion.

Cursor’s precedence is the strictest, and it is enforced at the dashboard: administrators can mark a Team Rule as enforced, which makes it required for all team members and not disableable in Customize. The same docs include the sentence that matters most for a compliance use case, which is that AI guidance should not be your only security control.

The trap that will cost you a morning

Anthropic’s support for AGENTS.md has a condition that is not obvious and has its own troubleshooting section in the docs.

By default, the setting called Project instructions is claude-md-or-agents-md. Under that default, Claude reads your AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or any directory above it. If one of those exists, your AGENTS.md is ignored.

The part that produces the support ticket is that CLAUDE.local.md counts. The documentation is explicit: because CLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you. A developer adds a gitignored local file to store personal notes, and the project’s shared instructions silently stop applying.

There are three more conditions on the same feature. Reading AGENTS.md directly requires Claude Code v2.1.277 or later, and before v2.1.281 some sessions, specifically those on Amazon Bedrock or with telemetry disabled, read CLAUDE.md files only. And a session where AGENTS.md support is unavailable will not show the Project instructions setting at all in the config panel, so you cannot fix it from the panel in the session that needs it.

One difference worth knowing if you rely on observability: InstructionsLoaded hooks fire for CLAUDE.md files but do not fire for an AGENTS.md read through the setting. If your hook-based logging is how you know which instructions loaded, it will look like nothing loaded.

The fix is documented and cheap. Either set Project instructions to claude-md-and-agents-md so both are read, or put an @AGENTS.md import in a CLAUDE.md next to it. Anthropic explicitly recommends the import over a symlink for one reason that will bite a lot of people: creating a symlink on Windows needs Administrator privileges or Developer Mode, and Git checks out a committed symlink as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line CLAUDE.md in place of your instructions.

Cursor ignores your markdown files

If you have been keeping .cursor/rules files, note that Cursor’s project rules must use the .mdc extension. A plain .md file in .cursor/rules is ignored by the rules system, because it has no frontmatter to specify description, globs, and alwaysApply. Cursor’s docs put it in a filename table as api-guidelines.md marked “Ignored (wrong extension)”.

Cursor also has richer application modes that AGENTS.md does not, driven by three frontmatter fields. alwaysApply: true includes the rule always and ignores globs and description. alwaysApply: false with globs auto-attaches when a matching file is in context. alwaysApply: false with a description and no globs lets Agent decide based on relevance. alwaysApply: false with neither is manual-only, applied when you @-mention the rule. So if your rules need to load conditionally, that capability lives in .mdc rather than in AGENTS.md.

Two documented limits on Cursor’s side are worth noting: rules do not impact Cursor Tab or other AI features, and User Rules are not applied to Inline Edit, only to Agent chat. If you are relying on instructions to shape inline edits, they are not there.

Nothing here is enforcement

The single most important sentence across all four documentation sets comes from Anthropic: Claude treats CLAUDE.md files as context, not enforced configuration. To block an action regardless of what the model decides, you need a PreToolUse hook.

That distinction changes how you should write the file. Claude’s content is delivered as a user message after the system prompt, not as part of the system prompt itself, so there is no guarantee of strict compliance, especially for vague or conflicting instructions. If an instruction must run at a specific point, such as before every commit or after each file edit, the vendor’s own answer is to write it as a hook, which executes as a shell command at fixed lifecycle events and applies regardless of what the model decides to do.

The writing advice is consistent across vendors and is worth following literally:

Two pieces of tooling make maintenance less of a chore than it sounds. Anthropic ships /doctor prompt-audit, which checks your instruction files for content written for older models, references to files or commands that do not exist, and instructions that contradict each other, and reports proposed edits without changing anything until you ask. And its /init command already reads other tools’ instruction files, specifically Cursor rules in .cursor/rules or .cursorrules and Copilot rules in .github/copilot-instructions.md.

One file, four readers, four limits Claude Code under 200 lines Codex stops at 32 KiB Cursor under 500 lines Ignored if a CLAUDE.local.md exists Conflicts resolved four different ways Context, never enforcement

VERDICT

Keep one AGENTS.md and size it for the strictest reader, which is Anthropic's 200 lines, not Codex's 32 KiB. The format settled: it is stewarded by the Agentic AI Foundation under the Linux Foundation, used by over 60,000 projects, and read by Cursor, Copilot, Codex, Gemini CLI, Aider, Windsurf, Devin, Zed, opencode, and others, so the days of maintaining four copies are over. Then handle the three things the shared format does not standardise. Check whether Claude Code is actually reading it, because the default setting skips AGENTS.md whenever a CLAUDE.md or CLAUDE.local.md sits above your working directory, and adding a gitignored CLAUDE.local.md is enough to silently disable your project's instructions; set Project instructions to claude-md-and-agents-md, or add an @AGENTS.md import, which is also the portable fix since committed symlinks break on Windows checkouts without core.symlinks. Assume no conflict resolution is shared, because the spec says the nearest file wins while Cursor enforces Team, Project, then User, and Anthropic states plainly that a user rule conflicting with a project rule may go either way. And write the file as guidance, not as a control, because Anthropic documents these files as context rather than enforced configuration delivered as a user message after the system prompt; anything that must happen at a fixed moment, like a check before every commit, belongs in a hook, and Cursor's own docs make the same point that AI guidance should not be your only security control.

Sources