AGENTS.md vs CLAUDE.md vs .cursorrules Compared

TL;DR: Use AGENTS.md for shared repository guidance, CLAUDE.md with @AGENTS.md for Claude Code, and .cursor/rules/*.mdc for Cursor-specific rules. Add path-scoped rules using each tool's documented format. Verify discovery and precedence in the actual client; one filename does not imply identical behavior across tools.

Key Takeaways

• AGENTS.md is plain Markdown with no required schema. Its discovery and scope are determined by the consuming tool.
• Claude Code documents an `@AGENTS.md` import in `CLAUDE.md`; this shares content without requiring duplicated conventions.
• Cursor `globs`, Copilot `applyTo`, and Claude Code `.claude/rules/` `paths` all provide path-scoped guidance. The original claim that only two formats support it was incorrect.
• Use Cursor's documented `.mdc` project-rule format; a Markdown file's presence alone does not prove it was loaded as a rule.
• For Codex, the instruction chain runs from the project root to the current working directory, with documented per-directory selection and size limits. Do not generalize that discovery algorithm to every agent.
• Instruction files guide model behavior. Enforce mandatory permissions, checks, and release gates through application controls, hooks, or CI.

Which files should a mixed-tool repository start with?

Official guidance checked September 11, 2026: AGENTS.md, Codex instruction discovery, Claude Code memory, Cursor rules, and Copilot repository instructions.

Conceptual monorepo example: assume a root JavaScript package and a separate services/api package, each with its own test command. Substitute commands that actually exist in your repository.

Do not put @AGENTS.md in every format and assume it imports: Claude documents that syntax, while other clients have their own discovery/reference behavior. The detailed examples below cover those differences. For how this fits a development lifecycle, see AWS AI-DLC.

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 required frontmatter or required set of sections. Client-specific discovery rules still apply.

That is a genuine trade-off, not a shortcoming. A shared plain-text format avoids requiring each client to implement the same metadata schema. AGENTS.md itself does not define glob metadata; consumers may scope nested files or impose loading limits. Consult the client documentation before assuming every file is loaded for every task.

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?

The official site lists participating clients, while each vendor documents its own support. Codex and Cursor document AGENTS.md; GitHub documents agent instructions for supported Copilot surfaces. Claude Code documents the explicit import bridge shown below.

For Codex specifically, global instructions and project instructions form a chain. Within a directory, AGENTS.override.md takes precedence over AGENTS.md; project discovery proceeds from the root toward the working directory, and nearer guidance can override earlier guidance. The documented default project_doc_max_bytes limit is 32 KiB. Starting in the repository root is not equivalent to starting in a nested package.

Record the client version, working directory, matching file paths, and any override file when diagnosing missing instructions. A compatibility badge does not establish that all clients use the same scope or precedence.

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.

Cursor documents project rules as .mdc files with description, globs, and alwaysApply metadata. Use that format and inspect whether the rule is applied. Plain Markdown can contain frontmatter too; the relevant distinction is the client's documented rule format, not Markdown's ability to hold metadata.

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. Without an import, its AGENTS.md conventions are not automatically loaded as Claude instructions; other Claude instructions may still provide project context. Two fixes:

The import form allows Claude-specific additions and avoids platform-dependent symlink setup. 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. Choose boundaries from distinct commands and constraints, rather than copying another repository's file count.

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 standard glob metadata. Consumers can use nested files for scope, but their discovery paths and loading limits differ. In Codex, verify the root-to-working-directory chain instead of assuming every directory touched later was loaded at startup.

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. Client context and discovery limits still apply; verify the guidance loaded from the intended working directory. 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.

Sources

• AGENTS.md format and consumer guidance
• OpenAI Codex AGENTS.md discovery and limits
• Claude Code memory, imports, and path-scoped rules
• Cursor project rules and AGENTS.md
• GitHub Copilot repository and path instructions