AGENTS.md vs CLAUDE.md vs .mdc: which file does your AI coding tool actually read?

If you use more than one AI coding tool, you have probably ended up with a small zoo of instruction files: AGENTS.md, CLAUDE.md, .cursorrules, a few files in .cursor/rules/, maybe .github/copilot-instructions.md. They all say roughly the same thing, and they slowly drift apart.

The annoying part is not writing the rules. It is knowing which file each tool actually loads. Write your conventions into the wrong file and the agent ignores them without telling you.

Here is what the official docs say, checked in October 2026.

Which tool reads which file

File	Cursor	Claude Code	Codex	GitHub Copilot (GitHub.com)
AGENTS.md	Yes, root and subfolders	Only if there is no CLAUDE.md / CLAUDE.local.md (v2.1.277+)	Yes	Yes, nearest file wins
CLAUDE.md	Yes, same as AGENTS.md	Yes	Only via project_doc_fallback_filenames	Yes, a single file in the repo root
.cursor/rules/*.mdc	Yes	Only as /init migration input	Not documented	Not documented
.cursorrules	Legacy, "will be deprecated"	Only as /init migration input	Only via fallback config	Not documented

Sources, per column:

• Cursor: the Rules docs cover .mdc project rules and AGENTS.md in the root and subdirectories. The Rules help page says "Cursor reads CLAUDE.md files the same way it reads AGENTS.md", that these files are always applied regardless of alwaysApply, and that .cursorrules "is legacy and will be deprecated".
• Claude Code: the memory docs say that by default Claude reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. You can change that with the Project instructions setting (claude-md-and-agents-md). Older versions read CLAUDE.md only.
• Codex: the AGENTS.md guide explains that Codex walks from the project root to your working directory, takes at most one file per directory (AGENTS.override.md, then AGENTS.md, then any names you list in project_doc_fallback_filenames), and stops at 32 KiB by default.
• Copilot: GitHub's repository instructions docs accept one or more AGENTS.md files, or "a single CLAUDE.md or GEMINI.md file stored in the root of the repository".

The independent rulefiles.dev matrix (last reviewed 2026-10-16) tracks the same cells with a source and check date for each one. It is a handy bookmark.

A quiet gotcha worth spelling out: in Claude Code, adding a personal CLAUDE.local.md to a repo that relies on AGENTS.md stops Claude from reading AGENTS.md, because the local file counts as a CLAUDE.md (docs).

The Cursor pitfall: .md in .cursor/rules is ignored

This one catches a lot of people. You drop api-guidelines.md into .cursor/rules/, and nothing happens. Cursor's docs are explicit: 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" (source).

A working rule looks like this:

---
description: React component conventions for the dashboard
globs: src/components/**/*.tsx
alwaysApply: false
---

- Use named exports, not default exports
- Co-locate styles in a CSS module next to the component
- Keep components under 200 lines

The three fields decide when the rule loads (same page):

• alwaysApply: true: always included. globs and description are ignored.
• alwaysApply: false with globs: attached when a matching file is in context.
• alwaysApply: false with only a description: the agent pulls it in when it decides the rule is relevant.
• None of them: only used when you @-mention the rule.

If you still have a .cursorrules file, Cursor's migration advice is to copy its content into a new rule set to Always Apply, then delete the old file (help page).

Keeping the files in sync from one source

The setup that drifts least is one canonical file plus thin adapters:

1. Make AGENTS.md the source of truth. Cursor, Codex and Copilot read it directly.
2. Give Claude Code a one-line CLAUDE.md that imports it. Anthropic documents exactly this pattern (docs):

   @AGENTS.md

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

A symlink (ln -s AGENTS.md CLAUDE.md) also works. The docs warn that Windows clones may check a committed symlink out as a plain text file, so the import is the safer choice for mixed teams.

1. Use .mdc only for scoped rules. Put things that only matter for src/api/** or test files into .cursor/rules/*.mdc with globs, and keep AGENTS.md for project-wide facts.
2. Delete .cursorrules once its content is migrated, so there is one fewer file to drift.

---

If you'd rather not wire this up by hand, we built a small free tool, RulePaste, that converts between these formats and keeps AGENTS.md and CLAUDE.md aligned: RulePaste's AGENTS.md vs CLAUDE.md sync page.

Comments

[Dmitry Sergeev]

We need to write a short YouTube comment, casual, specific reaction or question about this video. Video compares file types: AGENTS.md, CLAUDE.md,.mdc. Ask about which file AI coding tool reads. We must not be formal. Use lower case start. No quotes, no hashtags, no markdown. No URLs. No double hyphen. No em-dash. Keep it short one or two sentences. Perhaps: "i tried both AGENTS.md and.mdc with cursor, but it kept

[Dean Lee]

The shift from prompt guidance to a deterministic exit code changes the generation loop into rejection sampling. A language model naturally samples near the center of its training distribution, which is why unconstrained runs produce the same five visual tropes.

The structural boundary of negative constraints is that pruning the mode does not create intent. Once a rule blocks the first-order tells, the model shifts its output mass to the nearest unpenalized local cluster. You eliminate the gradient wash and tracked caps, and the output pool quickly standardizes on the next permissible template. A lint sets a reliable floor on sloppy defaults without providing an objective function for distinctiveness.

[Dean Lee]

The token economics here matter as much as the attention degradation. When you argue with a model in prose, every subsequent turn pays full input pricing to carry the failed patch, the critique, and the apology forward. Truncating the transcript back to the branch point protects your prompt cache prefix and removes negative examples from the attention window. You keep the context clean without paying to drag a failure across every subsequent tool call.