Which Source of Truth Does Your Coding Agent Believe?
Claude Code, Codex, Cursor, and Copilot each ship a different documented rule for whose instructions win when your files disagree. Here is what each one actually does, and what to do about the gap.
In brief: every major coding agent resolves conflicting instructions by position in a concatenated prompt, not by adjudicating which source is correct. The four leading agents order those sources differently, and two of them invert each other on whether the individual or the organization wins. Ranking your files is a real improvement over not ranking them, and it still leaves the harder problem untouched: nothing in that pipeline knows whether the doc it just read is current.
Your coding agent does not have a source of truth. It has a concatenation order.
Claude Code, Codex, Cursor, and GitHub Copilot all publish rules for whose instructions win when two files disagree, and those rules are not the same rules. One loads your organization's policy first and refuses to let you exclude it. Another ranks personal instructions highest and organization instructions last. A third merges everything and, by its own documentation, may pick between contradictory instructions arbitrarily. If you have been writing rules files on the assumption that precedence works the way it does in your head, that assumption is the gap.
What do coding agents actually do when sources conflict?#
They order text, then hope. A benchmark preprint published in April 2026, ConflictQA, instantiated conflicts between textual evidence and knowledge-graph evidence and found that models "often fail to identify reliable evidence for correct reasoning" and "tend to rely exclusively on either KG or textual evidence, resulting in incorrect responses."
That is the mechanism underneath every rules file you have written. When your wiki says one thing and your code does another, the agent reads a prompt in which one of them happens to appear later, or more often, or in a section its instructions told it to prefer. Position does the work that judgment appears to be doing.
The practical consequence is that your source of truth belongs to the tool. Move the same files to a different agent and the answer can change.
How does Claude Code resolve conflicting instructions?#
By concatenation, in a documented order, with an explicit warning that ties can break arbitrarily. Anthropic's memory documentation lists four CLAUDE.md scopes loaded from broadest to most specific: managed policy, user instructions, project instructions, then local instructions.
The important sentence is what happens next. "All discovered files are concatenated into context rather than overriding each other." There is no winner. Everything is present, ordered root-down, and the file closest to where you launched Claude is read last.
Anthropic is unusually direct about the failure mode: "if two rules contradict each other, Claude may pick one arbitrarily." The docs also note that CLAUDE.md is "context, not enforced configuration," delivered as a user message after the system prompt, with "no guarantee of strict compliance." For anything that must hold, Anthropic points you at hooks instead.
One asymmetry worth knowing: managed policy CLAUDE.md, deployed by IT at the OS level, cannot be excluded by individual settings. It is the only layer an organization can impose without a developer overriding it.
How does Codex merge AGENTS.md files?#
Root-down, with the nearest file last and a hard byte ceiling. OpenAI's Codex documentation states it plainly: "Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt."
The mechanism matches Claude Code, with the walk arranged so proximity wins. Codex starts in your Codex home directory, reading AGENTS.override.md if it exists and AGENTS.md otherwise, then walks the project tree toward your working directory. Depth in the tree decides which instruction survives, whatever your intent was.
The ceiling is where this gets interesting. Codex stops adding files once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB. In a monorepo with instructions at several levels, the files that get dropped are the ones furthest down the walk. Codex drops your most specific guidance first, and it never surfaces the truncation in the session.
The AGENTS.md spec that Codex implements is explicit that "explicit user chat prompts override everything," which makes the human in the loop the real top of the stack.
How does Cursor rank Team, Project, and User rules?#
Team first, user last, which inverts the intuition most engineers bring to it. Cursor's rules documentation gives an unambiguous ordering: "Rules are applied in this order: Team Rules → Project Rules → User Rules. All applicable rules are merged; earlier sources take precedence when guidance conflicts."
Cursor supports four application modes: always apply, apply intelligently based on the rule's description, apply to specific files by pattern, and apply manually by mention. Only the first is guaranteed to be in context. "Apply intelligently" delegates the decision to the model, which means a rule can be correctly authored, correctly scoped, and still absent from the session that needed it.
Cursor also reads nested AGENTS.md files, where "instructions from nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence." So a single repository can run two different precedence schemes at once: organizational-source order for .cursor/rules, and directory-proximity order for AGENTS.md.
How does GitHub Copilot prioritize instructions?#
Personal first, organization last, which is the exact reverse of Claude Code's managed policy model. GitHub's documentation states: "Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last."
Copilot reads repository-wide instructions from .github/copilot-instructions.md, path-specific instructions from .github/instructions/**/*.instructions.md, and increasingly the shared agent files such as AGENTS.md and CLAUDE.md, though GitHub notes those are not yet supported across all Copilot features.
On conflicts, the guidance is candid to the point of being an admission: "Whenever possible, try to avoid providing conflicting sets of instructions." GitHub does not offer a resolution rule. It tells you to avoid creating the conflict in the first place, and suggests disabling repository instructions temporarily when output quality degrades.
If your compliance team believes its standards outrank a developer's personal preferences, Copilot's documented order says otherwise.
The four agents disagree about your source of truth#
Because each vendor answered a different question. Anthropic optimized for enterprise control, GitHub for individual developer experience, Cursor for team consistency, and OpenAI for filesystem locality. All four are defensible positions. All four produce a different answer from the same set of files, and none of the four is written down anywhere in your repository.
| Agent | Highest-priority source | Documented conflict behavior | Hard limit |
|---|---|---|---|
| Claude Code | Managed policy (cannot be excluded) | Files concatenated, not overridden; may pick arbitrarily on contradiction | 200-line target per file for adherence |
| Codex | Nearest file to working directory | Root-down concatenation; nearest file appears last and wins | 32 KiB combined, silently truncated |
| Cursor | Team Rules | Merged; earlier sources take precedence | Only "always apply" rules are guaranteed present |
| GitHub Copilot | Personal instructions | No resolution rule; guidance is to avoid conflicts | Agent files unsupported in some features |
Read that table as a portability warning. A team running Cursor and Copilot side by side, which is common past fifty engineers, has two agents that resolve the same conflict in opposite directions. We cover the broader tradeoffs in Cursor vs Claude Code and Claude Code vs Codex CLI.
Frequently asked questions#
Does telling the agent "always trust the code over the docs" work?#
Partially. It helps when the code and the docs disagree about what exists today. It does not help when the code is correct for the old architecture and the migration is half-finished, because both sources are real code.
Should I rank sources of truth in my rules file?#
Yes. An explicit hierarchy is better than an implicit one, and it costs you twenty minutes. Just do not mistake it for enforcement. Every vendor above describes these files as context that shapes behavior, with no guarantee the agent complies.
Do nested files help or hurt?#
Both. Directory-proximity precedence is the right default for monorepos, and it is also how Codex ends up dropping your most specific instructions when the 32 KiB cap hits.
What about AGENTS.md as a single standard?#
It genuinely reduces duplication, and Claude Code reads CLAUDE.md rather than AGENTS.md, so Anthropic suggests importing one into the other. Standardizing the file does not standardize the precedence.
Why doesn't a bigger rules file fix this?#
Because adding context degrades the retrieval you already had. Chroma's context rot research, published July 2025 across 18 models including GPT-4.1, Claude 4, and Gemini 2.5, found that models do not "use their context uniformly" and that performance grows increasingly unreliable as input length grows. Single distractors measurably reduced accuracy, and focused prompts of roughly 300 tokens outperformed full prompts of roughly 113,000 on the same task.
A stale rule is a distractor with your team's name on it. It reads as authoritative, it sits near genuinely current instructions, and nothing in the pipeline marks it as expired.
The vendors concede the ceiling in their own limits. Anthropic targets under 200 lines per CLAUDE.md and warns that "longer files consume more context and reduce adherence." Codex truncates at 32 KiB. Both numbers say the same thing: the file cannot grow to cover your organization. The same budget pressure shows up in tool definitions, which we measured in MCP tool overload.
What settles your source of truth before the agent acts?#
Something that reads the sources at query time and ranks them by freshness and authority rather than by position in a file. That is the job a context engine does: institutional context for coding agents, assembled from PRs, Slack, Jira, Notion, and Confluence, with the contradiction settled before the agent starts writing.
The difference is where adjudication happens. A rules file records what was true when someone last edited it. Query-time retrieval can see that the ADR was superseded in March, that the Slack thread proposing the pattern ended in a rejection, and that the merged PR contradicts the wiki page still ranking first in search. The source of truth becomes something computed at the moment it is needed.
Teams feel this most when they have tried the manual version:
"Before Unblocked, I was manually compiling documentation into a local folder just so Claude Code could reference it. Now it pulls everything directly. I'm getting 90% accuracy on complex data structure questions that would have taken hours to figure out. It eliminated work that was genuinely mind numbingly arduous."
Austin Rojan — Onboarding Specialist, Subsplash
The stakes are in the trust numbers. The 2025 Stack Overflow Developer Survey found 45.7% of developers actively distrust AI accuracy against 32.7% who trust it, with only 3.1% highly trusting, while 84% use or plan to use the tools anyway. The top frustration, at 66%, is "AI solutions that are almost right, but not quite." Almost-right is what a confidently cited stale doc produces.
Run the disagreement test on your own repo#
Pick one thing your team changed in the last quarter where the old version is still documented somewhere: a deprecated endpoint, or a library you banned and never cleaned up. Then run four steps.
- Open a fresh session in each agent your team uses, with no hints and no prior conversation.
- Ask what the current approach is.
- Record which agents answer correctly and which recite the old decision.
- Check whether those results track the precedence order in the table above.
The test measures which file won, and by extension which source of truth your tooling settled on while nobody was watching. If one agent confidently repeats a decision that was reversed months ago, you have found your precedence order the expensive way, and the same failure shows up with deprecated APIs.
Then fix the cheap part first. Delete contradictory rules before you add a rule about which rule wins, since Anthropic tells you plainly that Claude may resolve a contradiction arbitrarily. Finding them by hand across CLAUDE.md, AGENTS.md, .cursorrules, and whatever accumulated under .cursor/rules/ is the tedious part, so we open-sourced repo-rules-agent under MIT to do it. It indexes every rules file in a repo, collapses the same rule phrased three different ways into a single record, and flags the contradictions so you know which ones to delete. The announcement post covers install. Then move anything that must hold into hooks or CI, where it is enforced.
DORA's 2025 State of AI-assisted Software Development describes AI as an amplifier that magnifies both the strengths of high-performing organizations and the dysfunctions of struggling ones. Precedence rules are where that amplification starts. Your agent will be exactly as consistent as the sources you point it at, and right now it is resolving those conflicts by counting bytes.
