AGENTS.md vs CLAUDE.md vs .cursorrules: Which Agent Instruction File Should Your Repo Use?

TL;DR: Four formats now compete to instruct AI coding agents. AGENTS.md is the open standard, read by more than 20 tools including Codex, Cursor, and Copilot's coding agent, and adopted in over 60,000 open-source repositories. Cursor's .cursor/rules/.mdc and Copilot's .github/instructions/.instructions.md add glob-based conditional loading that AGENTS.md's plain markdown cannot express. Claude Code reads CLAUDE.md and does not read AGENTS.md — bridge the two with a single @AGENTS.md import line. For a team on mixed tooling, keep one AGENTS.md as the source of truth and add thin tool-specific adapters that import it.

Key Takeaways

• AGENTS.md has no schema — the FAQ is explicit that no fields are mandatory and you may use any headings. Its value is a predictable location, not a structure, which is exactly why 20+ tools could adopt it without coordination.
• Claude Code does not read AGENTS.md. A one-line `@AGENTS.md` import in `CLAUDE.md`, or a `ln -s AGENTS.md CLAUDE.md` symlink, is the entire fix — but nobody tells you, so repos silently run Claude with zero project context.
• Only Cursor MDC rules and Copilot `.instructions.md` files support conditional loading by file path. This is the one capability plain AGENTS.md structurally cannot replicate, and it's the difference between a 500-line always-on prompt and a 40-line rule that appears when it's relevant.
• A plain `.md` file dropped in `.cursor/rules/` is silently ignored — the extension must be `.mdc`, because plain markdown has nowhere to put the `description`/`globs`/`alwaysApply` frontmatter.
• Nesting semantics differ in a way that matters for monorepos: AGENTS.md and Cursor resolve by proximity (nearest file wins), while Claude Code concatenates every file from filesystem root down to your working directory without overriding.
• Instruction files are context, not enforcement. Every vendor says so in different words. If a rule must hold every time — a lint gate, a blocked path — use a hook or CI check, not a bullet in a markdown file.

Why Did Every AI Coding Tool Invent Its Own Rules File?

The problem is old and boring: an AI agent opening your repository knows the code but not the conventions. It doesn't know you use pnpm and not npm, that API handlers belong in src/api/handlers/, that your commit messages follow a house format, or that the integration tests need a local Redis. So you re-explain it. Every session, forever.

Each vendor solved this the same way — a markdown file in a known location, loaded into context at session start — and each picked a different filename. By late 2025 a single polyglot repository could plausibly need .cursorrules, .github/copilot-instructions.md, CLAUDE.md, .windsurfrules, .clinerules, and .devin/rules/, all restating the same conventions and all drifting out of sync.

AGENTS.md is the reaction to that fragmentation. It came out of joint work between OpenAI Codex, Amp, Jules, Cursor, and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation — governance that matters, because a cross-vendor format owned by one vendor is just that vendor's format with better marketing.

What Exactly Is AGENTS.md, and What Is It Not?

AGENTS.md is best understood as a README for agents: a predictable place for the build steps, test commands, and conventions that would clutter a human-facing README. The split is deliberate — README.md stays focused on human contributors.

The critical design decision is the absence of a spec. Asked whether any fields are mandatory, the official FAQ answers: "No. AGENTS.md is just standard Markdown. Use any headings you like." There is no frontmatter, no required sections, no validator.

That is a genuine trade-off, not a shortcoming. Zero schema is why twenty-odd tools adopted it in months — there was nothing to disagree about. It is also why AGENTS.md cannot express conditional loading: there is no metadata layer to hold a glob pattern. Everything in the file is always in context.

Commonly used sections, none of them required:

Documented commands do get executed. The FAQ confirms agents will "attempt to execute relevant programmatic checks and fix failures before finishing the task" — so listing your test command is functionally different from describing it in prose.

Which tools read AGENTS.md?

Compatible out of the box: Codex, Jules, Factory, goose, opencode, Zed, Warp, VS Code, Devin, UiPath, Junie (JetBrains), Amp, RooCode, Kilo Code, Phoenix, Semgrep, Ona, Windsurf, Augment Code, Cursor, and GitHub Copilot's coding agent.

Two need one line of config each:

Adoption is past the tipping point: over 60,000 open-source projects, including openai/codex (Rust), apache/airflow (Python), temporalio/sdk-java, and PlutoLang/Pluto (C++).

How Do the Four Formats Actually Compare?

The columns are not really competing. AGENTS.md optimizes for breadth — one file, every tool, no metadata. The other three optimize for precision within one tool. A mature repo usually wants both.

How Do Cursor's MDC Rules Work?

Cursor's current model is .cursor/rules/, version-controlled and scoped to the codebase. The single-file .cursorrules at the repo root is the legacy form — still recognized in the wild and still parsed by migration tooling, but no longer the documented path. Cursor's docs now steer you to .cursor/rules/*.mdc or AGENTS.md.

The first gotcha bites nearly everyone: a plain .md file in .cursor/rules is ignored entirely. The extension must be .mdc, because plain markdown has nowhere to carry the description, globs, and alwaysApply fields that decide when the rule loads.

Three frontmatter fields produce four behaviors:

Note @src/api/schemas.ts — rule bodies can reference real files instead of pasting code, so the guidance stays current as the code changes.

Precedence runs Team Rules → Project Rules → User Rules. All applicable rules merge, and on conflict earlier sources win — the inverse of the "most specific wins" instinct most developers bring to config files. Team Rules can be marked enforced so members cannot toggle them off.

Two scope limits worth internalizing: rules do not affect Cursor Tab, and User Rules never reach Inline Edit (Cmd/Ctrl+K) — they serve Agent/Chat only. Cursor recommends keeping rules under 500 lines and splitting anything larger.

Cursor also honors AGENTS.md, in the root and in subdirectories, combining nested files with their parents so the narrower instruction wins.

How Do GitHub Copilot Instructions Work?

Copilot splits repository-wide from path-specific.

Repository-wide lives at .github/copilot-instructions.md and applies to every request in that repo's context. It's plain natural-language markdown; whitespace between instructions is ignored, so formatting is free.

Path-specific instructions are NAME.instructions.md files in or below .github/instructions, each opening with an applyTo glob:

excludeAgent ("code-review" or "cloud-agent") withholds a file from one consumer; omit it and both read the file. When a path-specific file and the repo-wide file both match, both sets are used — they compose rather than override.

One caveat with real consequences: on GitHub.com, path-specific instructions currently work only with Copilot cloud agent and Copilot code review. If you write a beautiful applyTo rule and test it in Copilot Chat in your editor, you may conclude it's broken when it simply isn't wired to that surface yet.

A detail that makes instructions self-testing: during PR review, Copilot reads instructions from the head branch, not the base — so you can validate a change to your instructions inside the same PR that introduces it.

Across scopes, personal instructions take highest priority, then repository, then organization — though all relevant sets are provided.

How Does Claude Code's CLAUDE.md Differ?

Claude Code loads four scopes, broadest to most specific:

The resolution model is the sharpest divergence from the others. Claude Code walks up the directory tree from your working directory and concatenates everything it finds — files do not override each other. Content is ordered from filesystem root down to your working directory, so instructions nearest your launch point are read last. Within a directory, CLAUDE.local.md is appended after CLAUDE.md. Files in subdirectories below your cwd aren't loaded at launch; they load on demand when Claude reads files there.

For a monorepo that means an ancestor's CLAUDE.md is additive context you didn't ask for. claudeMdExcludes is the escape hatch:

Imports use @path, resolve relative to the importing file, and recurse to a maximum depth of four hops. Import parsing skips code spans and fenced blocks, so ` @README in backticks stays literal while a bare @README imports the file — a distinction that has surprised people whose CLAUDE.md quietly pulled in a file they were only mentioning.

Path-scoped rules live in .claude/rules/ with paths: frontmatter:

Rules without paths load unconditionally at the same priority as .claude/CLAUDE.md. Brace groups multiply — {a,b}/{c,d}/*.{ts,tsx} expands to eight patterns — and a rule's whole paths list shares a budget of 1,000 expanded patterns.

Anthropic targets under 200 lines per CLAUDE.md, on the explicit grounds that longer files consume more context and reduce adherence. Splitting into @path imports helps organization but not context cost, since imports load at launch anyway.

Claude Code reads CLAUDE.md, not AGENTS.md. A repo that standardized on AGENTS.md runs Claude Code with no project context at all, and nothing warns you. Two fixes:

The import form is better when you want Claude-specific additions; the symlink is fine when you don't. On Windows, symlinks need Administrator or Developer Mode, so prefer the import. Verify either way with /context and look for CLAUDE.md under Memory files.

Migrating in the other direction, /init reads existing Cursor rules (.cursor/rules/ or .cursorrules) and Copilot rules (.github/copilot-instructions.md) and folds the relevant parts into a generated CLAUDE.md. With CLAUDE_CODE_NEW_INIT=1 it also reads AGENTS.md, .devin/rules/, .windsurf/rules/, and .clinerules.

Cursor, as an always-on rule (.cursor/rules/commits.mdc):

Note alwaysApply: true — commit messages aren't tied to a file pattern, so glob scoping is the wrong tool here. This is the case where "always" is correct.

Copilot (.github/copilot-instructions.md) takes the same prose. Claude Code takes it in CLAUDE.md, or inherits it from @AGENTS.md.

If the format must hold without exception, back it with a commit-msg hook. Which brings us to the limit of all four systems.

Anthropic is the most direct: CLAUDE.md content is "delivered as a user message after the system prompt, not as part of the system prompt itself," and there is "no guarantee of strict compliance, especially for vague or conflicting instructions." To block an action regardless of what the model decides, you need a PreToolUse hook. Cursor's equivalent advice is to skip wholesale style guides and let a linter own them.

Single-tool team. Use that tool's native format and take the metadata. Cursor-only: .cursor/rules/*.mdc with globs. Claude Code-only: CLAUDE.md plus .claude/rules/. Skipping AGENTS.md costs you nothing today, and adding it later is a rename.

Monorepo. Nested files per package, and pay attention to which semantics you're getting. AGENTS.md and Cursor resolve by proximity — nearest wins, cleanly. Claude Code concatenates ancestors additively, so reach for claudeMdExcludes to keep other teams' instructions out. For scale calibration: OpenAI's main repo carries 88 AGENTS.md files, so per-package granularity is a proven pattern, not over-engineering.

Migrating from .cursorrules. Split the monolith by concern into .cursor/rules/*.mdc — remembering the .mdc extension — and glob-scope everything that is genuinely path-specific. Anything universal (commit format, security rules) either stays alwaysApply: true or moves up to AGENTS.md where every other tool can see it too.

Whichever you pick, verify the file actually loaded rather than assuming. Claude Code: /context, check Memory files. Copilot Chat on GitHub.com: expand the references list and look for .github/copilot-instructions.md. Cursor: if a rule seems inert, check its type — Apply Intelligently needs a description, Apply to Specific Files needs a pattern that genuinely matches. A rule that never loads is indistinguishable from a rule the model ignored, and the two have completely different fixes.

No. Claude Code reads CLAUDE.md and does not read AGENTS.md. If your repository standardizes on AGENTS.md, create a CLAUDE.md containing the single line @AGENTS.md so both tools read the same instructions without duplication, and add any Claude-specific guidance below the import. A ln -s AGENTS.md CLAUDE.md symlink also works when you don't need Claude-specific content, though on Windows symlinks require Administrator privileges or Developer Mode, so the import is the safer default. Confirm it loaded by running /context and checking that CLAUDE.md appears under Memory files.

Effectively yes. Cursor's current documentation covers only .cursor/rules/*.mdc and no longer presents the root-level .cursorrules file as the recommended path, though the legacy file remains widespread and is still recognized by migration tooling — Claude Code's /init, for example, reads both .cursor/rules/ and .cursorrules when generating a CLAUDE.md. The practical reason to migrate is capability rather than compliance: .cursorrules is a single always-on file, while .mdc rules carry description, globs, and alwaysApply frontmatter that lets a rule load only when a matching file is in context. That conditional loading is what keeps large rule sets from consuming context on every request.

State the commit-message language explicitly in your instruction file, and state it independently of the conversation language — agents otherwise tend to mirror whatever language you're chatting in. In AGENTS.md or CLAUDE.md, a line such as "Write commit messages in English only, regardless of the language of our conversation" is sufficient. In Cursor, put it in a .cursor/rules/commits.mdc rule with alwaysApply: true, since commit formatting isn't tied to any file glob. For Copilot, .github/copilot-instructions.md takes the same prose. If the convention must hold without exception, enforce it with a commit-msg git hook, because instruction files are context that shapes behavior rather than a hard enforcement layer.

Three of the four do, and plain AGENTS.md does not. Cursor uses a globs field in .mdc frontmatter, GitHub Copilot uses applyTo in .github/instructions/.instructions.md, and Claude Code uses a paths list in .claude/rules/.md. All three accept standard glob syntax where matches one path segment and *` recurses through directories. AGENTS.md has no metadata layer at all — the official FAQ confirms no fields are mandatory and it is just standard markdown — so its entire contents are always in context. AGENTS.md approximates path scoping through nested files in subdirectories, where the nearest file to the edited file takes precedence.

How many AGENTS.md files should a monorepo have?

One per package or logical boundary, plus a root file for repository-wide conventions. Resolution is proximity-based: agents read the nearest file in the directory tree, nested instructions combine with their parents, and the narrowest applicable instruction wins on conflict. Explicit user prompts override everything. There is no practical ceiling — OpenAI's main repository carries 88 AGENTS.md files — so treat per-package granularity as the normal pattern rather than over-engineering. Keep the root file limited to conventions that genuinely apply everywhere, and push framework- or language-specific guidance down to the package that owns it, which also keeps each file short enough to be followed reliably.