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

RulePaste — Fri, 30 Oct 2026 16:48:58 +0000

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:

Make AGENTS.md the source of truth. Cursor, Codex and Copilot read it directly.
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.

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.
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.

DEV Community: RulePaste

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

Which tool reads which file

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

Keeping the files in sync from one source

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