AGENTS.md vs CLAUDE.md vs .cursorrules: Which Agent Instruction File to Use

A team that adopted Cursor in 2024, added Claude Code in 2025, and is now trying Codex can easily end up with three instruction files that each say how to run the tests. Someone fixes the command in one of them after a CI change. The other two keep the old one, and each agent follows whichever copy it happened to load.

The choice between AGENTS.md, CLAUDE.md, and .cursorrules used to be a choice of tool. As of October 2026 it mostly is not. Codex, Claude Code, and Cursor can all read AGENTS.md, so make AGENTS.md the one file you edit, keep CLAUDE.md as a one-line import of it, and use .cursor/rules/ only for rules that need Cursor's file scoping. The details of what each tool loads, and in which order, decide whether that setup works in your repository.

Each file started as one tool's convention

AGENTS.md is an open format, a plain Markdown file with no required fields. The format came out of work across OpenAI Codex, Amp, Google's Jules, Cursor, and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. The agents.md site says it is used by over 60,000 open source projects (checked October 30, 2026). The format supports nested files in a monorepo, and its stated conflict rule is that the closest AGENTS.md to the edited file wins, with explicit chat prompts overriding everything.

CLAUDE.md is Claude Code's instruction file. Claude Code reads it at four scopes: an organization-managed file, a user file at ~/.claude/CLAUDE.md, a project file at ./CLAUDE.md or ./.claude/CLAUDE.md, and a gitignored CLAUDE.local.md for personal project notes. A CLAUDE.md can pull in other files with @path imports, up to four hops deep. Claude Code also reads rules from .claude/rules/, which can be scoped to file paths.

.cursorrules is Cursor's original single file at the project root. Cursor's help center calls it legacy and says it "will be deprecated." Its replacement is a folder of project rules at .cursor/rules/*.mdc, where frontmatter (description, globs, alwaysApply) sets one of four modes: always apply, let the agent decide from the description, apply to files matching a glob, or apply only when @-mentioned. A plain .md file in that folder is ignored.

Which tool reads which file

The table below is drawn from each tool's own documentation, checked October 30, 2026.

Two rows are easy to miss. Cursor reads CLAUDE.md, and applies it to every Agent conversation regardless of frontmatter, so anything you write there for Claude Code also reaches Cursor. Codex reads only the filenames it is configured for, so a repository that keeps its conventions in CLAUDE.md alone gives Codex nothing unless that name is configured as a fallback.

What each agent loads in a repo that has all three

Suppose your repository root has AGENTS.md, CLAUDE.md, .cursorrules, and a few .mdc rules, and nobody has changed any defaults.

Codex walks from the project root (usually the Git root) to your working directory. In each directory it takes AGENTS.override.md if present, otherwise AGENTS.md, otherwise a configured fallback name, and includes at most one file per directory. It concatenates them root first, so files nearer your working directory come later in the prompt and take precedence. It stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. Your CLAUDE.md and Cursor rules never load.

Claude Code finds a CLAUDE.md, so under its default claude-md-or-agents-md setting it reads your CLAUDE.md files and skips AGENTS.md. It concatenates every CLAUDE.md from the filesystem root down to the working directory instead of letting one replace another. Subdirectory files load when Claude reads or edits a file in that subdirectory. Its docs warn that if two instructions contradict each other, "Claude may pick one arbitrarily."

Cursor applies AGENTS.md and CLAUDE.md, plus whichever .mdc rules match their mode and the legacy .cursorrules. Its docs rank Team Rules over Project Rules over User Rules when guidance conflicts, but do not rank AGENTS.md against CLAUDE.md. Rules apply only to Agent (Chat), not to Tab completion, Inline Edit, or Bugbot reviews.

So in this repository Codex reads AGENTS.md, Claude Code reads CLAUDE.md, and Cursor reads both. If the two files disagree about the test command, each agent acts on a different one, and Cursor gets both versions in the same context.

Keep one source of truth for all three

The setup that holds up across the three tools has four parts.

1. Put shared conventions in AGENTS.md. Build and test commands, layout, review rules. Codex and Cursor read it natively. Use nested AGENTS.md files in packages that need different instructions.
2. Make CLAUDE.md a thin import beside each AGENTS.md. Once a CLAUDE.md exists, Claude Code's default skips direct AGENTS.md loading, so a first line of @AGENTS.md brings the shared text in. Add that companion file at the root and in each package with its own AGENTS.md. A root import loads the root file, not every nested file. The import also works on versions before 2.1.277 and when someone adds a personal CLAUDE.local.md. Cursor sees the one-line CLAUDE.md plus the AGENTS.md it reads natively.
3. Move tool-specific instructions out of the shared files. Rules only Claude Code should follow go in .claude/rules/, which Cursor's rules docs do not list. Rules that need glob scoping in Cursor go in .cursor/rules/*.mdc, which Codex and Claude Code do not read. Avoid Claude-only text in CLAUDE.md itself, since Cursor always applies that file.
4. Delete .cursorrules. Cursor's migration steps are to create a project rule, paste the content, set it to Always Apply, and remove the old file. If the content is general, move it into AGENTS.md instead.

The whole CLAUDE.md can be one line.

@AGENTS.md

Symlinks are an option, with two catches

The agents.md FAQ suggests renaming to AGENTS.md and symlinking the old name for compatibility (ln -s AGENTS.md CLAUDE.md in this case). A symlink avoids a second file, but it has two costs. Git for Windows disables symlink support by default unless Developer Mode is on, and with core.symlinks set to false, Git checks a symlink out as a small plain file containing the link text, so Claude Code on that machine reads a file that says AGENTS.md and nothing else. And Cursor reads both filenames. Its docs do not say whether it deduplicates a symlinked pair, so check the Rules list in Cursor's Customize panel before assuming it loads the text once. The import has neither problem.

If your team prefers CLAUDE.md as the canonical file, configure project_doc_fallback_filenames = ["CLAUDE.md"] for Codex. You can put it in ~/.codex/config.toml for personal use or commit it in the repository's .codex/config.toml for a shared default. Codex loads project configuration only in trusted projects. The fallback applies only in directories without AGENTS.override.md or AGENTS.md.

Consolidating does not keep the file current

One file fixes the three-copies problem. A single file can still be wrong. An instruction file changes only when someone edits it, and the pull request that renames a test command or moves a service does not touch it unless the author remembers. Imports, nesting, and glob scoping decide where instructions load. None of them notice that the code moved.

Our post A stale AGENTS.md is worse than no AGENTS.md covers why that failure is quiet, and Best Tools to Keep AGENTS.md Files Up to Date compares the options for catching drift, from CI scanners to PR-time review.

Which setup fits your team

• One tool, one repo. Use the native file. For Claude Code that is CLAUDE.md, for Codex AGENTS.md. For Cursor, use AGENTS.md for plain instructions and .cursor/rules/*.mdc when you need file-pattern scoping. Adding AGENTS.md costs little if a second tool is likely.
• Two or more tools. AGENTS.md as the file you edit, a one-line CLAUDE.md import, tool-specific rules in .claude/rules/ and .cursor/rules/, and no .cursorrules.
• Large monorepo. A short root AGENTS.md plus nested files per package, each with a companion CLAUDE.md importing its local AGENTS.md. Codex reads the directories between the root and where you start it. Claude Code loads a nested CLAUDE.md and its import when it reads files in that subtree. Cursor combines nested AGENTS.md instructions with the parent files, giving the more specific instructions precedence. Watch Codex's 32 KiB combined cap and Claude Code's guidance to keep each CLAUDE.md under 200 lines.

FAQ

Does Claude Code read AGENTS.md?

Yes, on v2.1.277 and later, by default 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 in /config, for example to claude-md-and-agents-md to load both. An @AGENTS.md import in CLAUDE.md also works on older versions and under the default setting.

Is .cursorrules deprecated?

Cursor's help center says the file "is legacy and will be deprecated," and gives migration steps to a project rule set to Always Apply. The docs describe it as legacy rather than removed. New rules should go in .cursor/rules/*.mdc or AGENTS.md.

Does Cursor read CLAUDE.md?

Yes. Cursor's docs say it reads CLAUDE.md the same way it reads AGENTS.md and always applies it, regardless of any alwaysApply frontmatter. Use .cursor/rules/ when you need conditional rules in Cursor.

Do subdirectory files override root files?

Codex and Claude Code keep the root file. Both concatenate from the root down, so the more specific file comes later and Codex treats it as taking precedence, while Claude Code warns that contradictory instructions may be resolved arbitrarily. Cursor combines nested AGENTS.md files with their parents and gives more specific instructions precedence. Keep nested files to what differs from the root rather than restating it.

Check what each agent is loading

Run this from your repository root to inventory common repository-local instruction files. It skips Git metadata and dependency directories:

find . -type d \( -name .git -o -name node_modules \) -prune -o \( -type f -o -type l \) \( -name AGENTS.md -o -name AGENTS.override.md -o -name CLAUDE.md -o -name CLAUDE.local.md -o -name .cursorrules -o -path '*/.claude/rules/*.md' -o -path '*/.cursor/rules/*.mdc' \) -print

Check configured fallback names, imported files, user settings, and organization policies separately. Then ask each tool what it loaded. In Claude Code, run /context and read the Memory files list. In Codex, run codex --ask-for-approval never "Summarize the current instructions." In Cursor, open the Rules list under Customize. Any two files that state the same command differently are your first fix.

Once the shared files are in place, keep them tied to the code they describe. An organization admin can create a Dosu Library, add the GitHub repository as a Source, import your AGENTS.md, and turn on a Monitor for the repo. When the Monitor detects that a pull request makes a published Document stale, it drafts an edit for your team to accept, edit, or decline on that pull request.