AGENTS.md vs CLAUDE.md vs Cursor Rules: Which File Loads (2026)

Last verified: October 8, 2026 against each tool's official docs, linked in the table below. These loading rules change often. Recheck the docs before you restructure a large repo.

Short answer: Use AGENTS.md as the shared source of truth, since Cursor, Codex, GitHub Copilot and Claude Code can all read it. Claude Code reads AGENTS.md directly from v2.1.277, but by default only when no CLAUDE.md or CLAUDE.local.md exists. For Claude-only rules, add a CLAUDE.md that imports @AGENTS.md. Use .cursor/rules only for Cursor-specific, glob-scoped rules.

This page used to be a short note called "keep one AGENTS.md." The advice still holds, but the Claude part changed: Claude Code can now load AGENTS.md on its own. So here is the full, dated version, built from the vendors' docs rather than from other blogs.

The short answer

Pick one of these three setups. Each is explained in detail further down.

Your situation	Commit this	Why
Same rules for every agent, nothing tool-specific	AGENTS.md only	Every tool in the table below can read it (Gemini CLI after one setting), and there is one file to keep current
You also want a few Claude-only instructions	AGENTS.md plus a short CLAUDE.md that starts with @AGENTS.md	Claude reads the shared file through the import, then your Claude lines, and never loads AGENTS.md twice
Some folders need rules that only Cursor should apply	AGENTS.md plus .cursor/rules/*.mdc	Cursor's globs frontmatter attaches a rule only when matching files are in context

Which agent reads which file

Tool	Files it reads for project instructions	Reads AGENTS.md?	Official doc
Claude Code	CLAUDE.md or .claude/CLAUDE.md, CLAUDE.local.md, ~/.claude/CLAUDE.md, a managed policy CLAUDE.md, and .claude/rules/*.md	Yes, from v2.1.277. By default only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md is in the working directory or above it	Claude Code memory docs
Cursor	.cursor/rules/*.mdc project rules, User Rules, Team Rules, AGENTS.md, and a root CLAUDE.md	Yes, in the project root and in subdirectories	Cursor rules docs and Cursor rules help
OpenAI Codex	AGENTS.override.md or AGENTS.md in ~/.codex, then one file per directory from the project root down to the working directory, plus any names in project_doc_fallback_filenames	Yes, it is the main file	Codex AGENTS.md guide
GitHub Copilot	.github/copilot-instructions.md, .github/instructions/**/*.instructions.md (with applyTo), and agent instructions	Yes, for agent instructions, with support that varies by feature and editor. The cloud agent and Copilot CLI also accept CLAUDE.md or GEMINI.md	Copilot repository instructions and Copilot support matrix
Gemini CLI	GEMINI.md by default, global and per project, plus just-in-time files when a tool touches a folder	Only if you add it to context.fileName in settings.json	Gemini CLI GEMINI.md docs

Two details in that table matter more than they look:

• Copilot support is not uniform. The support matrix lists AGENTS.md for Copilot Chat in VS Code, the cloud agent and Copilot CLI, but Copilot Chat in Visual Studio lists only copilot-instructions.md and path-specific files. If your team relies on one surface, check that row.
• Cursor also reads CLAUDE.md. Cursor's help page says it reads CLAUDE.md the same way it reads AGENTS.md and always applies it, whatever its frontmatter says. Anything you put in a Claude adapter file is visible to Cursor too.

The AGENTS.md project site describes the format as plain Markdown with no required fields, and notes that the closest AGENTS.md to the edited file wins.

How Claude Code decides between CLAUDE.md and AGENTS.md

This is where most of the confusion online comes from. Several older guides say Claude Code ignores AGENTS.md. That is out of date. Here is what the Claude Code docs say as of October 8, 2026.

The default rule

The docs give a three-row table. If the repo has an AGENTS.md and no CLAUDE.md or CLAUDE.local.md in your working directory or above it, Claude reads AGENTS.md. If it has both, Claude reads "your CLAUDE.md files only." If a CLAUDE.md already imports AGENTS.md, Claude reads the CLAUDE.md with AGENTS.md included through the import.

What counts for that check: a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. What does not count: your personal ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and .claude/rules/ files. Those keep loading alongside AGENTS.md.

When AGENTS.md wins, Claude reads every AGENTS.md and .claude/AGENTS.md from the working directory upward, expands @path imports inside them, and applies claudeMdExcludes. It does not read AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ directory. That last point matters if you share a repo with Codex users who rely on AGENTS.override.md.

The CLAUDE.local.md gotcha

Because CLAUDE.local.md counts as a CLAUDE.md, adding one quietly turns AGENTS.md off for you. A common story: the team relies on AGENTS.md, you create a gitignored CLAUDE.local.md for your sandbox URL, and suddenly Claude forgets the team's test commands. The docs name this case directly. The fix they give is to set Project instructions to claude-md-and-agents-md.

The Project instructions setting

Type /config in a session and change Project instructions. The docs list four values:

• claude-md-or-agents-md: the default. CLAUDE.md files, or AGENTS.md files when no CLAUDE.md or CLAUDE.local.md exists.
• claude-md-and-agents-md: both, with each directory's CLAUDE.md files first and its AGENTS.md after. An AGENTS.md already loaded through an import or symlink is not read twice.
• claude-md: CLAUDE.md files only.
• managed-only: only the managed CLAUDE.md and auto memory at launch.

You can also set it in ~/.claude/settings.json under pluginConfigs for the built-in plugin cc-plugin-agents-md@builtin (the docs note the older ID agents-md@builtin before v2.1.285). Claude Code ignores that entry in project and local settings files, so you cannot force it for the whole team from the repo.

Do you still need the CLAUDE.md that imports AGENTS.md?

Often not, but it does no harm. The docs say a CLAUDE.md containing @AGENTS.md "you can leave," and that keeping the import never makes Claude read AGENTS.md twice. Keep it if the file also holds Claude-only lines, or if some sessions cannot load AGENTS.md directly. The docs list those cases: versions before v2.1.277, the built-in plugin turned off with /plugin, and sometimes the first session after upgrading from v2.1.276 or earlier.

Two older workarounds should go. A CLAUDE.md that only says "read AGENTS.md" in words relies on Claude choosing to open the file, so replace it with an @AGENTS.md import or delete it. A SessionStart hook that prints AGENTS.md now adds a second copy, so remove it. Our older walkthrough, How to Make CLAUDE.md Import AGENTS.md, still covers the import pattern for those sessions.

Cursor: .cursorrules vs .cursor/rules vs AGENTS.md

Cursor's help page says the root .cursorrules file "is legacy and will be deprecated." The migration it gives: create a new rule, paste the old content, set the type to Always Apply, and delete .cursorrules.

Project rules live in .cursor/rules and must use the .mdc extension. A plain .md file there is ignored. Three frontmatter fields control when a rule loads:

• alwaysApply: true puts it in every chat.
• globs with alwaysApply: false attaches it when a matching file is in context.
• description alone lets the agent pull it in when the description looks relevant.
• With none of them, the rule loads only when you @-mention it.

Glob-scoped rules earn their place when one folder has sharp edges: migrations, generated code, a vendored SDK. Everything else can live in AGENTS.md, which Cursor describes as the simple alternative to .cursor/rules. Note that rules only apply to Agent (Chat). Cursor's help page says they do not affect Tab completion, Inline Edit or Bugbot reviews.

Three repo setups you can copy

Setup 1: AGENTS.md only

Use this when every agent should follow the same rules. Here is a minimal skeleton for a fictional repo:

# AGENTS.md

## What this repo is
tidepool-api: a REST API for tide station readings.

## Commands that work
- Install: npm ci
- Test: npm test
- Lint: npm run lint

## PR bar
- Tests pass and new endpoints have a test.
- Migrations include a down step.

## Never
- Print or commit values from .env files.
- Invent station IDs. Read them from fixtures/stations.json.
- Call the live data feed in unit tests.

## Path exceptions
- db/migrations: never edit a migration that is already merged.

The AGENTS.md plus Cursor .mdc Compiler from a Repo Brief writes this file from a short repo brief and refuses to invent commands or globs. For a Codex-first team, the Codex CLI AGENTS.md from Repo Brief prompt does the same job.

Setup 2: AGENTS.md plus a thin CLAUDE.md

Use this when Claude needs a few extra lines. The Claude Code docs show this exact shape:

@AGENTS.md

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

Claude reads the imported AGENTS.md first, then the lines below it. Remember that Cursor also reads a root CLAUDE.md, so keep the Claude section harmless for other tools. If you need no Claude-specific content at all, the docs say ln -s AGENTS.md CLAUDE.md also works, with two caveats: Claude's Edit and Write tools refuse to write through the symlink, and Windows clones may check it out as a one-line text file. On mixed teams, prefer the import. The CLAUDE.md Adapter that Imports AGENTS.md prompt drafts this thin file.

Setup 3: AGENTS.md plus Cursor .mdc rules

Keep the shared policy in AGENTS.md and move one folder's sharp edges into a scoped rule:

---
description: Safety rules for SQL migrations
globs: db/migrations/**/*.sql
alwaysApply: false
---

- Every migration has an up and a down step.
- Never change a column type in place. Add, backfill, then drop.

Save it as .cursor/rules/migrations.mdc. The Cursor AGENTS.md and Project Rules MDC Generator and Cursor Rules .mdc from a Repo Brief build these with valid frontmatter. The walkthrough How to Compile AGENTS.md and Cursor mdc from a Repo Brief shows the full flow. Claude Code has its own version of scoped rules: .claude/rules/*.md with a paths field, which is the only frontmatter field Claude reads there.

What to put in AGENTS.md (and what to leave out)

Write only facts you can prove from the tree:

• What the repo is for, in one or two lines.
• Commands that actually run today: install, test, lint, dev.
• What a pull request must include.
• A never-list: files, APIs and guesses the agent must not make.
• Where secrets live, and that agents must never print them.
• Path exceptions: folders with extra rules.

Leave out versions nobody pinned, style rules your linter already enforces, and long procedures. The Claude Code docs suggest keeping each CLAUDE.md under 200 lines, and Cursor's docs suggest keeping rules under 500 lines. Codex stops adding instruction files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default.

Instructions are guidance, not enforcement. The Claude Code docs say so plainly and point to hooks for anything that must always happen. If a rule has to hold every time, such as formatting after edits or blocking a command, pair it with a hook. The Claude Code Hooks Config Writer drafts one.

Monorepos and nested files

Each tool handles nested files a little differently:

• Cursor: nested AGENTS.md files apply when you work in that folder, combined with the parent files, with the more specific one taking precedence.
• Codex: walks from the project root down to the working directory and includes at most one file per directory, with AGENTS.override.md beating AGENTS.md at the same level.
• Copilot: the nearest AGENTS.md in the directory tree takes precedence.
• Claude Code: loads instruction files above the working directory at launch and subdirectory files on demand. A subdirectory's AGENTS.md loads when Claude reads a file there and that folder has no CLAUDE.md of its own. In big monorepos, claudeMdExcludes can skip other teams' files.

Because the rules differ, put shared policy at the root and keep nested files short and folder-specific.

Common mistakes

• Adding a CLAUDE.local.md and losing AGENTS.md. Switch Project instructions to claude-md-and-agents-md.
• Keeping a .cursorrules file. Cursor calls it legacy. Move it into an Always Apply .mdc rule.
• Saving Cursor rules as .md. Cursor ignores them in .cursor/rules.
• Expecting Gemini CLI to find AGENTS.md by itself. Add it to context.fileName.
• Relying on AGENTS.override.md for Claude. Codex reads it. Claude Code does not.
• Writing three files from memory. They drift. Edit AGENTS.md first, then regenerate the adapters.

FAQ

Should I use AGENTS.md or CLAUDE.md?

Use AGENTS.md as the shared file. Add a CLAUDE.md only for Claude-specific lines, and make it import @AGENTS.md.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277, according to the Claude Code docs. By default it reads AGENTS.md only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working directory or above.

Why isn't Claude Code loading my AGENTS.md?

The docs list three checks: a CLAUDE.md or CLAUDE.local.md on the path, a version older than v2.1.277, or Project instructions set to claude-md or managed-only. Run /memory to see whether its path is listed.

Do I need both CLAUDE.md and AGENTS.md?

No. AGENTS.md alone works for Claude Code on current versions. Add CLAUDE.md only for Claude-only content or for sessions that cannot load AGENTS.md.

Is .cursorrules deprecated?

Cursor's help page calls it legacy and says it will be deprecated. Use .cursor/rules/*.mdc or AGENTS.md.

Does Cursor read AGENTS.md? Does GitHub Copilot?

Cursor reads it in the root and in subdirectories. Copilot reads it for agent instructions, but support depends on the feature and editor, so check GitHub's support matrix.

Can I symlink CLAUDE.md to AGENTS.md?

Yes, per the Claude Code docs, if you need no Claude-specific content. The import is safer on teams with Windows users.

What should go in AGENTS.md?

Working commands, the PR bar, a never-list, the secrets policy and path exceptions. Leave out anything you cannot prove from the repo.

Generate these files with PromptDig

• AGENTS.md plus Cursor .mdc Compiler from a Repo Brief
• CLAUDE.md Adapter that Imports AGENTS.md
• GitHub Copilot instructions.md Generator
• Aider Conventions File from a Repo Brief
• Claude Code Slash Command from a Repeatable Job
• How to Make CLAUDE.md Import AGENTS.md

More in the Coding prompts hub and the Agents prompts hub, or Browse more prompts.