Does Cursor Read AGENTS.md? Setup + vs CLAUDE.md (2026)

If you searched "does Cursor read AGENTS.md", you probably already have the file and you want a straight answer plus a working setup. Here it is, verified against the current vendor docs on 23 August 2026, followed by the honest comparison of AGENTS.md, CLAUDE.md, Cursor Rules and Copilot instructions — because the answer to "which one do I actually keep?" changed in 2026, and most guides on this topic are still describing 2025.

The short version: AGENTS.md won the portability argument, but it did not replace the vendor formats, and one very widely repeated claim — that Claude Code reads AGENTS.md — is flatly wrong according to Anthropic's own documentation.

Does Cursor read AGENTS.md?

Yes, natively and without any setting to flip. Cursor's Rules documentation describes four rule types, and AGENTS.md is one of them, sitting alongside Project Rules, User Rules and Team Rules. The docs describe it as "a simple markdown file for defining agent instructions" and tell you to "place it in your project root as an alternative to .cursor/rules for straightforward use cases."

Three practical consequences worth knowing:

• No frontmatter, no schema. AGENTS.md is plain markdown. That is the whole point of the format.
• It is not second-class. Cursor's own docs actively recommend it over dropping a plain .md file into .cursor/rules — a .md file in that folder is silently ignored, because the rules system needs the .mdc extension and frontmatter.
• The Cursor CLI reads it too. The CLI docs state: "The CLI also reads AGENTS.md and CLAUDE.md at the project root (if present) and applies them as rules alongside .cursor/rules."

Cursor was also one of the parties that shaped the format in the first place — agents.md credits the convention to collaboration between OpenAI Codex, Amp, Google Jules, Cursor and Factory. This was never a case of Cursor grudgingly bolting on a rival standard.

Where exactly does Cursor look for AGENTS.md?

Two places, and one place people assume but that does not exist.

A typical monorepo layout looks like this:

project/
  AGENTS.md              # repo-wide defaults
  frontend/
    AGENTS.md            # React/Tailwind conventions
    components/
      AGENTS.md          # component-specific rules
  backend/
    AGENTS.md            # service + migration rules

There is a subtle difference between the spec and Cursor's implementation that is worth knowing before you rely on it. The AGENTS.md FAQ says "the closest AGENTS.md to the edited file wins" — a pure nearest-file-wins model. Cursor's docs describe something softer: "instructions from nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence." So in Cursor, a nested file layers on top of its parents rather than replacing them. If your root file says "always use pnpm" and a nested file says nothing about package managers, Cursor still applies the root rule. Write nested files as deltas, not as standalone replacements.

How do I set up a global AGENTS.md for Cursor?

You can't — not as a file, anyway. This is the single most common false assumption about Cursor's rules system, and it produces the "my global AGENTS.md is being ignored" bug reports. Cursor has no home-directory AGENTS.md location. It has three sanctioned ways to get instructions applied across every project:

• User Rules. Defined in Customize → Rules inside Cursor, stored in your Cursor environment rather than in a repo file. They apply across all projects. Caveat straight from the docs: User Rules are used by Agent (Chat) only — they are not applied to Inline Edit (Cmd/Ctrl+K), and no rule type affects Cursor Tab.
• Team Rules. Available on Team and Enterprise plans, managed from the Cursor dashboard, applied across every repository for everyone on the team. They are free-form text (no folder structure), support a glob pattern for file-scoped application, and can be marked "Enforce this rule" so individuals cannot toggle them off.
• Remote rules imported from GitHub. Under Customize → Rules → Add Rule → Remote Rule (GitHub), point Cursor at a repository of .mdc files. Cursor scans the repo and syncs them into .cursor/rules/imported/<repoName>, preserving relative paths. This is the closest thing to "one shared rule set, many projects" that Cursor officially supports.

If you genuinely want a single file on disk that every repo picks up, the pragmatic workaround is a symlink: keep a canonical copy at ~/agents/AGENTS.md and link it into each checkout with ln -s ~/agents/AGENTS.md AGENTS.md, adding the link to your global gitignore so you never commit it. It works because Cursor only cares that a file resolves at the project root — but understand that this is a filesystem trick, not a supported feature.

One genuine exception: Skills do have a global location. Cursor's Agent Skills docs load SKILL.md packages from ~/.agents/skills/ and ~/.cursor/skills/ as well as project-level .agents/skills/ and .cursor/skills/. So the answer to "how do I share agent behaviour across every project" is often "make it a skill, not a rules file."

How does AGENTS.md interact with .cursor/rules?

They coexist. AGENTS.md is not a replacement for .cursor/rules and does not disable it — Cursor loads both. The difference is expressiveness. Project Rules live in .cursor/rules as .mdc files with YAML frontmatter, and three fields determine when each rule enters the context window:

A concrete example:

---
description: RPC service conventions for the backend
globs: src/services/**/*.ts
alwaysApply: false
---

- Define each service in its own file under `src/services/`
- Validate inputs at the service boundary before internal calls
- Return structured errors with a `code` and `message`; never throw raw strings

On conflicts, Cursor's documented precedence for the three rule types is Team Rules → Project Rules → User Rules, with all applicable rules merged and earlier sources winning when guidance conflicts. Note what is missing from that list: the docs do not slot AGENTS.md into the ordering. In practice, treat AGENTS.md as your always-on baseline and use .mdc rules when you need conditional activation, then avoid writing directly contradictory instructions in both — because the resolution order is not documented, and undocumented behaviour changes.

Cursor's own guidance is to keep rules under 500 lines and split large ones into composable files. For the rest of the Cursor workflow, see our Cursor IDE complete guide.

Does Cursor still support .cursorrules?

Cursor's current Rules documentation does not mention .cursorrules anywhere. It documents exactly four rule types — Project Rules, User Rules, Team Rules and AGENTS.md — and the legacy single-file format is absent from all of them.

That is the meaningful signal. Legacy .cursorrules files still exist in thousands of repositories and other tools still read them (Claude Code's /init, for example, explicitly scans ".cursor/rules/ or .cursorrules" when generating a CLAUDE.md). But an undocumented format receives no new features: none of the glob scoping, per-rule activation modes, agent-selected rules, or team enforcement described above works with it. If you are still on .cursorrules, migrate — and the cheapest migration is not to .mdc at all. Rename it to AGENTS.md. You get a plain-markdown file that Cursor documents, plus roughly two dozen other agents read it for free.

Does Cursor read CLAUDE.md?

The Cursor CLI does; the docs say so explicitly. The IDE's Rules documentation does not list CLAUDE.md as a rule type. So if you have a CLAUDE.md-only repo and you run cursor-agent in the terminal, your instructions load. Open the same repo in the Cursor editor and you should not count on it.

The safe configuration for a mixed Claude Code + Cursor team is an AGENTS.md holding the shared content, with a CLAUDE.md that imports it — which is exactly what Anthropic recommends, and the subject of the next section.

Does Claude Code read AGENTS.md?

No. This is the most consequential correction in this article, and Anthropic states it in one sentence in the Claude Code memory docs: "Claude Code reads CLAUDE.md, not AGENTS.md."

The documented fixes are an import or a symlink. The import is better because it lets you append Claude-specific rules underneath:

# CLAUDE.md
@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

Or, if you need nothing Claude-specific, ln -s AGENTS.md CLAUDE.md. On Windows a symlink needs Administrator rights or Developer Mode, so prefer the import there. Running /init also reads Cursor and Copilot rule files and folds the relevant parts into a generated CLAUDE.md; with CLAUDE_CODE_NEW_INIT=1 set it additionally reads AGENTS.md, .devin/rules/, .windsurf/rules/ and .clinerules. There is also a /import command that copies another agent's configuration — including instruction files, MCP servers, commands, subagents and skills — into Claude Code; it requires Claude Code v2.1.213 or later.

How does CLAUDE.md work in 2026?

CLAUDE.md gained a great deal since the three-layer model most guides still describe. There are now four file locations, loaded broadest-scope-first, and — importantly — they are concatenated rather than overriding one another:

Three additions matter for anyone comparing formats:

• .claude/rules/ closes the glob gap. Claude Code now supports a rules directory of plain .md files, discovered recursively, each optionally carrying a paths: YAML frontmatter list of globs so it only loads when Claude touches matching files. There is a user-level ~/.claude/rules/ too, loaded before project rules. Functionally this is Cursor's .mdc auto-attach behaviour, in plain markdown. Cursor's biggest structural advantage over CLAUDE.md is gone.
• Auto memory. Separately from anything you write, Claude keeps its own notes per repository at ~/.claude/projects/<project>/memory/, with a MEMORY.md index whose first 200 lines (or 25KB) load into every session. It is on by default; toggle it with /memory or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
• Imports and size limits. @path/to/file imports expand at launch, up to four hops deep. Anthropic targets under 200 lines per CLAUDE.md, skips any file over 4 MiB, and offers claudeMdExcludes to ignore other teams' files in a monorepo.

How do GitHub Copilot's instruction files work?

Copilot is the most permissive of the four: it reads almost everything. GitHub's coding agent added AGENTS.md support on 28 August 2025, root or nested, on top of the pre-existing .github/copilot-instructions.md and .github/instructions/**.instructions.md formats — and it reads CLAUDE.md and GEMINI.md as well.

Coverage is not uniform across surfaces, though. Per GitHub's custom-instructions support reference, .github/copilot-instructions.md is supported everywhere; AGENTS.md is supported in Copilot Chat (VS Code, JetBrains, Xcode), the coding agent (github.com, VS Code, JetBrains, Eclipse, Xcode), code review on github.com, and the Copilot CLI; while CLAUDE.md and GEMINI.md are honoured by the coding agent and CLI but not by Chat or code review.

In VS Code specifically (docs updated 19 August 2026), AGENTS.md support is governed by the chat.useAgentsMdFile setting and defaults to the workspace root only — nested AGENTS.md files require the experimental chat.useNestedAgentsMdFiles setting. That is a real portability trap: a nested layout that works perfectly in Cursor is, by default, only partially read in VS Code. VS Code's stated conflict order is personal instructions, then repository instructions, then organization instructions, and it explicitly warns that .instructions.md files and AGENTS.md are peers with "no specific order guaranteed" between them.

Which tool reads which file?

This is the table to bookmark. Verified against each vendor's own documentation on 23 August 2026.

The row that changed most in 2026 is SKILL.md. It began as an Anthropic-only format for task-scoped capabilities — a packaged folder with a SKILL.md, optional scripts/, references/ and assets/, invoked only when its description matches the task. Cursor now loads skills from .claude/skills/, ~/.claude/skills/, .codex/skills/ and ~/.codex/skills/ for compatibility, alongside its own .cursor/skills/ and the vendor-neutral .agents/skills/. A skill written for Claude Code now runs in Cursor unchanged. That is the second cross-vendor convention to actually take hold, after AGENTS.md itself.

Meta's Muse Code, launched 5 August 2026, is more evidence the format war is over: there is no MUSE.md. It adopted AGENTS.md and reads CLAUDE.md as a fallback. Our Muse Code complete guide covers its configuration model.

How do these formats handle monorepos?

All four have an answer, and they differ in shape more than in capability:

• AGENTS.md — directory nesting. One file per package, more specific instructions taking precedence. In Cursor, nested files layer onto their parents; the spec's own wording is closest-file-wins. In VS Code, nesting is off unless you enable the experimental setting.
• CLAUDE.md — the directory hierarchy above your working directory loads at launch; files in subdirectories load on demand when Claude reads files there. Use claudeMdExcludes to drop other teams' files.
• .cursor/rules — glob-driven rather than nested. A single backend.mdc with globs: services/api/** behaves like a nested file but lives centrally. Nested .cursor/rules directories are also discovered.
• Copilot — one .github/copilot-instructions.md plus .github/instructions/*.instructions.md scoped by applyTo; the coding agent additionally honours nested AGENTS.md.

Does an AGENTS.md actually improve agent output?

Less than the ecosystem assumes, and it is worth knowing before you write a 400-line file. A study from ETH Zurich researchers — Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (Gloaguen, Mündler, Müller, Raychev and Vechev, arXiv:2602.11988, submitted February 2026 and revised June 2026) — found that "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average."

The nuance in the abstract is the actionable part: instructions in context files are followed well by coding agents, but repository overviews — the architecture summaries that every template and every /init command loves to generate — are not helpful. That aligns with what both vendors now tell you independently. Anthropic's /doctor checkup proposes trimming exactly this content, cutting "directory layouts, dependency lists, and architecture overviews" while keeping "pitfalls, rationale, and conventions that differ from tool defaults." Cursor's docs say the same thing in different words: don't copy style guides (use a linter), don't document commands the agent already knows, don't duplicate what's in the codebase.

So: write commands and constraints, not descriptions. Anything the agent could discover by reading three files is costing you tokens for nothing.

Which file should you actually adopt?

For the deeper treatment of what belongs inside one of these files, see our AGENTS.md complete guide, and for the wider landscape of tools that consume them, the AI coding agents complete guide.

FAQ

Does Cursor read AGENTS.md?

Yes. Cursor's Rules documentation lists AGENTS.md as one of four first-class rule types, alongside Project Rules, User Rules and Team Rules. Cursor reads it from the project root and from any subdirectory, with no setting to enable and no frontmatter required. The Cursor CLI reads it too, and additionally reads CLAUDE.md at the project root.

Where do I put a global AGENTS.md for Cursor?

Nowhere — Cursor has no home-directory AGENTS.md location, and files at ~/.cursor/AGENTS.md are ignored. Use User Rules in Customize → Rules for personal cross-project instructions, Team Rules on Team and Enterprise plans for org-wide ones, or import a shared .mdc rule set from GitHub. A symlink from a canonical file into each repo root also works, unofficially.

Can I have both AGENTS.md and CLAUDE.md in the same repo?

Yes, and you often should, because Claude Code does not read AGENTS.md. Anthropic's documented pattern is to keep the shared content in AGENTS.md and make CLAUDE.md a one-line @AGENTS.md import, adding Claude-specific rules beneath it. A symlink (ln -s AGENTS.md CLAUDE.md) works if you need nothing Claude-specific.

Does Cursor still support .cursorrules?

Cursor's current Rules documentation does not mention .cursorrules at all — it documents exactly four rule types and the legacy single-file format is not among them. Existing files may still be picked up, but the format gets no new capabilities: no globs, no activation modes, no team enforcement. Rename it to AGENTS.md and roughly two dozen agents will read it.

Does AGENTS.md override .cursor/rules in Cursor?

Neither overrides the other; Cursor loads both. Its documented precedence covers only the three rule types — Team Rules, then Project Rules, then User Rules, all merged with earlier sources winning conflicts — and does not place AGENTS.md in that order. Treat AGENTS.md as your always-on baseline and avoid writing directly contradictory instructions in both.

How do nested AGENTS.md files behave?

In Cursor, nested files are combined with their parent directories, with the more specific instructions taking precedence — so a nested file layers onto the root rather than replacing it. The AGENTS.md spec itself describes stricter closest-file-wins behaviour. In VS Code, nesting is off by default and needs the experimental chat.useNestedAgentsMdFiles setting.

Does GitHub Copilot read AGENTS.md?

Yes, since 28 August 2025 for the coding agent, root or nested. Support varies by surface: AGENTS.md works in Copilot Chat on VS Code, JetBrains and Xcode, in the coding agent, in code review on github.com, and in the Copilot CLI. .github/copilot-instructions.md remains the only format supported everywhere.

How long should an AGENTS.md or CLAUDE.md be?

Anthropic targets under 200 lines per CLAUDE.md and skips files over 4 MiB entirely; Cursor tells you to keep a rule under 500 lines and split larger ones. Research on repository context files found they raise inference cost by over 20% on average without reliably improving success, and that architecture overviews specifically don't help. Write constraints, not descriptions.

Are these files safe to commit?

Yes, as long as they contain conventions rather than credentials. Every one of these formats is designed to be version-controlled and read by external services, so treat them as public. The exceptions built for private content are CLAUDE.local.md and Cursor User Rules, which stay on your machine — but even those should point at a secret manager rather than hold secrets.

The decision rule

Start with a single AGENTS.md at your repo root. It is the only file that Cursor, Copilot, Codex, Gemini CLI, Zed, Windsurf, Jules, Devin, Junie and roughly fifteen others all read without configuration. Add a CLAUDE.md that imports it the moment anyone on the team uses Claude Code, because that is the one major agent that will not read AGENTS.md. Add .cursor/rules/*.mdc or .claude/rules/ only when you hit a real need for glob-scoped activation — not before. And keep all of it short: the measured cost of a bloated context file is real, and the measured benefit of a repository overview is not.

Last reviewed 23 August 2026 against Cursor's Rules and CLI documentation, Anthropic's Claude Code memory documentation, GitHub's custom-instructions reference, the VS Code custom-instructions docs, and agents.md.