· Eric Brown

CLAUDE.md, AGENTS.md and Cursor Rules: Which One Wins When They Disagree

Does Claude Code read AGENTS.md? Which rule wins in Codex and Cursor? A precedence table for all three, the default that leaves many AGENTS.md files unread by Claude, and how to fix it.

If you run Claude Code, Codex and Cursor in the same repo, each one reads its own set of instruction files and settles conflicts its own way. Most days nobody notices, until two agents ship two different conventions in the same week and the difference turns up in code review.

Here's what each tool reads and which rule wins, taken from each tool's own docs. I last checked all of it on November 13, 2026. These tools change every few weeks, so check the linked docs if you're reading this much later.

Claude Code Codex Cursor
Main file CLAUDE.md (also .claude/CLAUDE.md and CLAUDE.local.md) AGENTS.md (or AGENTS.override.md) Project rules in .cursor/rules/*.mdc, plus AGENTS.md
Reads AGENTS.md? Only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it (the default). Your own ~/.claude/CLAUDE.md doesn't count. Needs v2.1.277 or later Yes Yes, in the root and in subdirectories
Reads CLAUDE.md? Yes No, unless you add it to project_doc_fallback_filenames The docs don't mention it
Several files apply All of them are combined, from the filesystem root down to your working directory. Files in subdirectories load when Claude works on a file there One file per directory, joined from the root down, up to 32 KiB by default (project_doc_max_bytes) Team Rules, then Project Rules, then User Rules, all merged
Which wins on a conflict No winner. "If two instructions contradict each other, Claude may pick one arbitrarily" The file closer to your working directory, because it comes later in the prompt "Earlier sources take precedence," so Team beats Project beats User. Between nested AGENTS.md files, the more specific one wins. The docs don't say where AGENTS.md ranks against Team rules

Sources: Claude Code memory docs, Codex AGENTS.md guide, Cursor rules docs. The AGENTS.md spec itself says "the closest AGENTS.md to the edited file wins; explicit user chat prompts override everything."

When Claude Code skips AGENTS.md

By default, Claude Code reads AGENTS.md only when no CLAUDE.md exists in the working directory or anywhere above it. If a repo has both files, Claude Code reads the CLAUDE.md and the AGENTS.md never reaches it. That's the documented default, and it's easy to miss because nothing tells you it happened.

It's also common. Decoding AI checked 815 active top repos in September and found 283 that ship an AGENTS.md. 161 of those (56.9%) also had a CLAUDE.md beside it, so Claude Code never falls back to the AGENTS.md. The original article won't open for me, so I'm relying on a summary of it and a post from one of the people behind it. The count doesn't check whether those CLAUDE.md files import the AGENTS.md, which would fix it. It also can't see CLAUDE.local.md files (those are usually gitignored), so 161 is a floor for repos where the fallback can't fire.

CLAUDE.local.md counts as a CLAUDE.md for this check. If one person on a team that relies on AGENTS.md adds a CLAUDE.local.md for their own notes, Claude Code stops reading the AGENTS.md for that person and nobody else. Everyone else's agent follows the team rules, and theirs doesn't.

The Claude Code docs give you three ways to fix which files get read:

  • Put @AGENTS.md at the top of your CLAUDE.md. Claude Code expands the import, so both agents read the same rules from one file. It's committed to the repo, so it works for everyone on the team. This is the one I'd start with.
  • Change Claude Code's Project instructions setting from the default claude-md-or-agents-md to claude-md-and-agents-md. Claude then reads both, each directory's CLAUDE.md first, and skips an AGENTS.md it already loaded through an import. This setting lives in each person's own settings (/config or ~/.claude/settings.json) or in your organization's managed settings. A project settings file committed to the repo is ignored. That makes it the right fix for the CLAUDE.local.md case, and a team-wide fix only if you manage settings centrally.
  • Symlink one file to the other, if you want a single file on disk.

To confirm it worked, run /context all in a new session and check that your CLAUDE.md appears under Memory files (on 2.1.280 or later, an AGENTS.md that Claude reads directly is listed there too). On Claude Code 2.1.283 or later, /doctor prompt-audit reads your CLAUDE.md, CLAUDE.local.md and AGENTS.md files and reports the ones that contradict each other.

When the rules disagree

Getting every agent to read the same file doesn't settle what happens when two rules in it disagree, or when a teammate's rule contradicts yours. The table answers that differently for each tool: Codex takes the closer file, Cursor takes the earlier source, and Claude Code may take either one. None of them stops to tell you while it's working. The prompt audit finds a contradiction only when somebody runs it.

In one small test where a rule lived only in AGENTS.md, Claude Code skipped it in both of its runs and Codex followed it in both. In the tester's words, "0/4 flagged the conflict." Four runs don't prove much on their own. The larger study I wrote about earlier this month found that Claude Code mentioned the conflict between the rules file and the code in 79 of 80 runs and followed the file anyway.

So somebody on the team has to hear about the disagreement and make the call once, and then every agent has to get that call.

Scout, the tool we're building, keeps team decisions in one record that Claude Code, Codex and Cursor all reach through the same MCP connection. When two current entries on the same subject disagree, Scout flags the conflict at the start of every session until somebody settles it, keeping one and recording why. It doesn't read your rules files, so it won't catch a Cursor rule that disagrees with your AGENTS.md. Its entries reach the agent through a tool call, which models weigh less than the rules file, so each agent's instruction file still needs a line telling it to check Scout. The import fix above comes first either way.

For Monday, a quick check of your own repo:

  • Do you have both a CLAUDE.md and an AGENTS.md? If so, does the CLAUDE.md import the AGENTS.md?
  • Does anyone on the team keep a CLAUDE.local.md in a repo that relies on AGENTS.md?
  • Is everyone's Claude Code at v2.1.277 or later? Older versions don't read AGENTS.md at all, and sessions on Amazon Bedrock or with telemetry turned off need v2.1.281.
  • Are your combined Codex AGENTS.md files under 32 KiB? Codex stops adding files at the limit, and since it adds them from the root down, the files closest to your working directory (the ones meant to win) are the likeliest to be left out.
  • Are your Cursor project rules saved as .mdc? A plain .md file in .cursor/rules is ignored.
  • Do your Cursor Team rules and your AGENTS.md say the same thing? Team rules beat project rules in Cursor, and the docs don't say how they rank against AGENTS.md, so keep the two in agreement.

Start the trial. 15 days. Every seat. Card up front, nothing charged until day 15. Plug into the record and stop repeating yourself to machines.

START THE TRIAL