AI Context Files: CLAUDE.md, AGENTS.md and Cursor Rules Compared

AI context files are the Markdown files a coding agent reads before it starts work: build commands, conventions, what never to touch. Claude Code reads CLAUDE.md, and reads AGENTS.md when there is no CLAUDE.md. OpenAI’s Codex reads AGENTS.md. GitHub Copilot reads .github/copilot-instructions.md, path-specific .instructions.md files and, on most agent surfaces, AGENTS.md. Cursor reads .mdc rules in .cursor/rules, plus AGENTS.md and a root CLAUDE.md. AGENTS.md is the one file all four understand, which makes it the natural source of truth, with each tool’s own file kept short and pointed at it.

The reference: file, place, reader

• AGENTS.md: at the repository root and optionally in any subfolder. Plain Markdown, no required fields. Read by Codex, Cursor, GitHub Copilot’s agents and many other tools; Claude Code reads it when you have no CLAUDE.md.
• CLAUDE.md: ./CLAUDE.md or ./.claude/CLAUDE.md in the project, ~/.claude/CLAUDE.md for you in every project, and CLAUDE.local.md for your own uncommitted notes. Read by Claude Code. Cursor’s rules help page↗ (opens in a new tab) says it always applies a root CLAUDE.md; Copilot’s cloud agent and CLI accept one at the root.
• .claude/rules/*.md: topic files for Claude Code, loaded every session or, with paths frontmatter, only when Claude reads matching files. VS Code reads them for sessions on its Claude harness.
• .github/copilot-instructions.md: GitHub Copilot’s repository-wide file. The one file every Copilot chat surface reads.
• .github/instructions/*.instructions.md: Copilot’s path-specific files, attached when an applyTo glob matches.
• .cursor/rules/*.mdc: Cursor’s project rules, each with frontmatter (alwaysApply, description, globs) that decides when it loads. A root .cursorrules file is the legacy form.

Support changes often. GitHub keeps a support table for custom instructions↗ (opens in a new tab) by surface, and some Copilot chat surfaces still read neither AGENTS.md nor CLAUDE.md. That surface-by-surface detail is in does GitHub Copilot support AGENTS.md?

Scope: whose rules are these?

Each tool separates rules for the project, rules for you, and rules set by an organisation, but the files differ.

• Project, committed with the code: CLAUDE.md and .claude/rules/, AGENTS.md, .github/copilot-instructions.md and .instructions.md files, .cursor/rules/.
• Personal, in your home folder or settings: ~/.claude/CLAUDE.md and CLAUDE.local.md for Claude Code; ~/.codex/AGENTS.md for Codex; personal instructions for Copilot; user rules in Cursor’s settings.
• Organisation: a managed CLAUDE.md deployed by IT; organisation instructions for Copilot; team rules from Cursor’s dashboard.

Project files travel with the repository and reach every colleague’s agent. Personal and organisation files do not, which is why anything a project depends on belongs in a committed file.

Precedence: what happens when several apply

This is where the tools differ most, and where most confusion starts.

• Claude Code: files are concatenated, not overridden. Its memory documentation↗ (opens in a new tab) says files above the working directory load at launch in order from the filesystem root down, so the one nearest where you started is read last; files in subfolders load when Claude reads files there. With both AGENTS.md and CLAUDE.md present, it reads CLAUDE.md only by default, a choice you can change with the Project instructions setting.
• Codex: concatenates from the Git root down to the current directory, checking AGENTS.override.md before AGENTS.md in each folder. OpenAI’s AGENTS.md guide↗ (opens in a new tab) says files closer to your directory override earlier guidance because they appear later, and that Codex stops adding files at a size limit, 32 KiB by default.
• The AGENTS.md convention: the agents.md↗ (opens in a new tab) site states that the closest AGENTS.md to the edited file wins, and explicit chat prompts override everything.
• GitHub Copilot: the nearest AGENTS.md in the directory tree takes precedence. Personal instructions rank above repository instructions, which rank above organisation ones, but all of them are sent.
• Cursor: team rules, then project rules, then user rules; the earlier wins in a conflict. Nested AGENTS.md files combine with their parents, and the more specific one wins.
• VS Code: its custom instructions page↗ (opens in a new tab) says instruction sources are additive, and warns against relying on file order or precedence to resolve conflicts, because behaviour differs by harness.

The practical rule follows from VS Code’s warning. In every tool, two contradictory lines both reach the model, and it picks one. Do not design a layout that depends on one file beating another. Write each rule once, in one place.

Imports and nesting

• Claude Code expands @path imports inside CLAUDE.md, and inside an AGENTS.md it reads. Relative paths resolve from the importing file, imports can nest four hops deep, and a path in backticks stays literal. Imports outside the project ask for approval the first time. Imported files still load in full, so they organise instructions but do not save space.
• Cursor rules can reference a file with @filename to pull it into the rule’s context, which keeps an example in one place.
• AGENTS.md itself is plain Markdown with no import syntax of its own. A tool that does not expand imports reads @path as text, so a file that leans on imports only works fully in the tools that expand them.
• Nesting works in all four: a subfolder file for one package, read when the agent works there. In a monorepo, that is how each app gets its own commands without the root file growing. How Claude Code behaves across several repositories is in managing multiple projects with CLAUDE.md.

Rules for some files only

Three tools solve the same problem, rules that apply only to some files, with three syntaxes: paths frontmatter in .claude/rules/, applyTo in Copilot’s .instructions.md, and globs in Cursor’s .mdc. There is no shared format, so a migration rule written for one tool has to be written again for another. Keep these files few and small, and put rules that apply everywhere in AGENTS.md.

One source of truth

The layout that works across all four keeps the content in AGENTS.md and makes every other file either a pointer or a short, tool-specific addition.

AGENTS.md                         # the rules: build, test, layout, never-touch, how work is tracked
apps/web/AGENTS.md                # overrides for work inside apps/web
CLAUDE.md                         # @AGENTS.md, then only Claude-specific lines
.github/copilot-instructions.md   # the few non-negotiables, written out in full
.claude/rules/migrations.md       # paths: db/**
.cursor/rules/migrations.mdc      # globs: db/**

• Start CLAUDE.md with @AGENTS.md, the approach Anthropic documents for sharing one file with other tools. Where Claude Code reads AGENTS.md directly, the import does not load it twice. On Windows, prefer the import to a symlink: the documentation notes that Git can check a symlink out as a plain text file.
• Remember that Cursor also applies a root CLAUDE.md. Anything Claude-specific you put there reaches Cursor’s agent too, so keep those lines harmless to other tools.
• Write the rules that must always hold out in full in .github/copilot-instructions.md, rather than pointing at AGENTS.md, because some Copilot chat surfaces never open AGENTS.md.
• Never keep two hand-synced copies of the same rules. They drift, and the drift is invisible until an agent follows the stale one.

Check what actually loaded

A file an agent never read does nothing. In Claude Code, /context lists what loaded under Memory files, and /memory opens them. In Copilot Chat, expand the references on a response to see which instructions file was used. Check after every change to the layout, not only when something goes wrong; a symlink checked out as text or a nested file that is switched off fails silently.

What does not belong in any of them

Context files describe how to work in a repository. They are the wrong place for what to work on, what was decided last week, or what one assistant learned that the next one needs, whichever tool that is. Those belong with the work. On fenbs, the board keeps AI context: short notes about how you work, for everything or for one project, which any connected assistant reads with fenbs_get_context before it starts. Put one line in AGENTS.md telling every agent to call it, and the notes reach Claude Code, Codex, Copilot and Cursor alike. Keeping a file lean in the first place is covered in context engineering for Claude Code and context engineering with GitHub Copilot.