CLAUDE.md and AGENTS.md: what happens with conflicting information? Is there a precedence order?
In Claude Code there is no precedence order: every CLAUDE.md it finds is concatenated into context,
nothing overrides anything, and Anthropic's docs say that if two instructions contradict each other
“Claude may pick one arbitrarily.” Codex and Cursor do define a winner (the closest AGENTS.md
for Codex; Team → Project → User rules for Cursor), but in every tool that ordering is a hint to the model,
not a guarantee. The only reliable fix is to keep each rule in exactly one place.
The question comes from a
Claude Code GitHub issue
asking how CLAUDE.md discovery works. The maintainer's reply was blunt: all the files are included at launch, so
“you need to take care to not include conflicting instructions.” That is still the answer, and the docs now spell out the details.
Which file wins, tool by tool
| Tool | What loads | On conflict |
|---|---|---|
| Claude Code | Managed, user (~/.claude/CLAUDE.md), every CLAUDE.md / CLAUDE.local.md from the filesystem root down to your working directory, plus .claude/rules/. Subdirectory files load when Claude reads a file there. |
No winner. Files are concatenated, root first, so the closest file is read last, but the docs say neither overrides the other. |
Claude Code + AGENTS.md |
By default, AGENTS.md is read only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. |
If a CLAUDE.md exists, AGENTS.md is skipped entirely, unless you import it or switch on the claude-md-and-agents-md mode. |
| Codex | Global ~/.codex/AGENTS.md (or AGENTS.override.md), then one file per directory from the project root down to your working directory, up to 32 KiB by default. |
Closer files override earlier guidance because they appear later. Files past the 32 KiB cap are not added at all. |
| Cursor | Team Rules, project rules (.cursor/rules/*.mdc), User Rules, and root and nested AGENTS.md, all merged. |
Team → Project → User, with earlier sources winning. Nested AGENTS.md: the more specific file wins. |
The AGENTS.md convention sums up the non-Claude tools: “The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.”
Why “closest wins” still is not a guarantee
- It is all one prompt. Every tool above puts both versions of the rule into the context window. “Precedence” only means one comes later or is labelled as more specific. The model still sees both and decides.
- Instruction files are advisory. Claude Code delivers
CLAUDE.mdas a user message after the system prompt, and Anthropic says there is no guarantee of strict compliance, “especially for vague or conflicting instructions.” - Built-in guidance can compete too. Your commit or PR rules can clash with the agent's own defaults. Claude Code lets you turn its built-in git instructions off (
includeGitInstructions) so only yours remain. - Big files make it worse. Anthropic recommends keeping each
CLAUDE.mdunder 200 lines because longer files reduce adherence, and a conflict buried on line 340 is harder for anyone, human or model, to spot.
A personal CLAUDE.local.md does not “correct” the shared CLAUDE.md. It sits beside it. And because it counts as a CLAUDE.md, adding one in a repo that relies on AGENTS.md stops Claude Code reading AGENTS.md for you.
How to find and remove conflicts
- List what actually loads. In Claude Code, run
/contextand read the Memory files list. In Cursor, check which rules are always on and which attach by glob. For Codex, walk the directories from the repo root to where you start it. - Paste every always-on file into Clogmeter. It flags exact and near-duplicate rules and likely always/never conflicts across files, and shows what each file costs in tokens.
- Pick one home per rule. Repo-wide facts go in the root file. Package-only conventions go in a nested file or a path-scoped rule, and are not restated at the root. Personal preferences go in your user file and should never contradict the project.
- Delete, do not override. If a nested file needs a different rule, remove or narrow the root rule (for example “Use pnpm, except in
legacy/, seelegacy/AGENTS.md”) instead of stacking a contradiction on top. - Move must-never-fail rules out of markdown. Use a hook, linter, or CI check. No precedence order makes prose enforceable.
- Re-check after big refactors. Claude Code's
/doctor prompt-audit(v2.1.283+) reports files that contradict each other. Otherwise, re-scan with Clogmeter.
Quick check
Weigh your files with the AGENTS.md / CLAUDE.md token counter or the Cursor rules token counter, then open the full inspector to see duplicates and conflicts side by side. Related reading: CLAUDE.md vs AGENTS.md vs Cursor rules and Keep AGENTS.md and CLAUDE.md from going stale.
Open Clogmeter and weigh your instruction files → Free, browser-only. Token counts, duplicates, conflicts, trimmed export — nothing uploaded.