DEV Community

Debashish Ghosal
Debashish Ghosal

Posted on AI-assisted

When AGENTS.md, CLAUDE.md, and a Skill Disagree, Which One Wins?

No referee exists for rule clashes

When AGENTS.md, CLAUDE.md, and a Skill Disagree, Which One Wins?

Your repo has AGENTS.md. Your tool added CLAUDE.md. A skill says the opposite.

Somewhere in that stack is a rule your agent will follow and rules it will silently ignore, and the documentation on which is which is thinner than the files themselves. So here is the smallest possible conflict to build, and a warning up front: there is no universal winner to report, and that instability is itself the finding.

Four Doors, No Bouncer

Instructions enter an agent from more places than most people track:

The repo file. AGENTS.md, the open standard adopted across harnesses. Repo-scoped, versioned, reviewed like code, in theory.

The tool file. CLAUDE.md and its cousins, per-harness convention files that often get created without a ticket and edited without a review.

The skills layer. Instruction files with their own provenance, which may have been written by your team, a marketplace, or a stranger with good SEO.

The runtime flags. Command-line settings and harness config that can override, extend, or quietly mute any of the above.

What is missing from this picture is the referee. There is no error message for conflicting instructions. The agent simply behaves according to whatever resolution order its harness applies, and you find out which rule won by observing the behavior, which is a terrible monitoring channel for policy conflicts.

The Ten-Minute Conflict Demo

You can run this yourself in ten minutes, which is the point: the demo requires no tooling and no permission from anyone.

Write three contradictory, harmless rules into the three instruction sources:

AGENTS.md: "When asked for a status word, respond only with ALPHA."

CLAUDE.md: "When asked for a status word, respond only with BRAVO."

The skill: "When asked for a status word, respond only with CHARLIE."

Then ask the agent for a status word, and see which letter comes back.

What makes the demo useful is not any single result. Harnesses differ, versions differ, and the resolution order is not stable across them, which means the finding is not "the repo file wins" or "the skill wins." The finding is that the answer is empirically determined per harness and per version, it fails silently, and almost nobody on your team knows which way your setup resolves.

Nobody can publish your letter for you, and I would not trust a universal one from anyone, because the answer is not stable across harnesses or versions. Run the demo on the exact harness and version your team uses, today. The letter that comes back is a fact about your stack, and until you have run it, your agents have been resolving the conflict for you, silently, the entire time.

tip: The conflict demo is free and its result is not stable across harness versions. Whatever letter you get, write it down with the date and the version, because after the next upgrade it is a stale answer pretending to be a current one.

What the Docs Actually Commit To

Reading the harness documentation on precedence, what stands out is the gap between what the docs promise and what teams assume.

The docs generally describe where each file is read from and which sources a harness consults, and that part is written down. What is thinner, often entirely absent, is a commitment to a conflict resolution order: not just "we read AGENTS.md and CLAUDE.md," but "when they disagree, this one wins." Silent, absent, and version-dependent is the honest summary of the state of precedence documentation, and you should verify the current behavior of your own harness rather than trusting this piece, because this is exactly the lane that changes under you.

The engineering conclusion from that gap: conflicts are resolved by implementation detail, and implementation detail is not policy. If your agent's compliance posture depends on precedence that no document promises, your compliance posture is a coincidence with good manners.

The Fix: Canonical Plus References

The resolution is boring and it is the same one that fixed this problem in every other layer of engineering: one source of truth, everything else points at it.

Declare one canonical instruction file for repo-level agent policy. Whatever your harness reads first and your team can actually review.

Everything else references it. CLAUDE.md becomes a pointer: "See AGENTS.md for all repo policy." Skills that need repo context say "repo policy applies" instead of restating it. No restated rules anywhere, because restatement is how conflicts are born.

Conflicts become diffs. Once there is one canonical file, a contradiction between instruction sources is visible in review, as text, instead of discoverable only by observing agent behavior after the damage.

The pattern is old. It is the same reason you have one canonical package manifest, one canonical config, one canonical schema. Instruction files got the same problem and deserve the same cure.

What I Would Check This Week

If you run agents from more than one tool against the same repo, the odds that you have two instruction files with at least one silent contradiction are high. Not malicious, not even wrong, just written at different times by different tools with different assumptions.

One evening: list your instruction files, grep them for rules about the same subjects, formatting, testing, commit style, and run the three-letter demo on your harness of record. Whatever letter you get, the team should know it, and the canonical-plus-references fix takes about the same amount of time as the audit that convinced you it was needed.

So here is the question, and the demo answers it in ten minutes: have you ever caught your agent following the wrong instruction file, and do you know, today, which one wins on your stack?

If the demo's letter surprises you, your agents have been resolving that conflict for you, silently, the entire time.

Top comments (18)

Collapse
 
jacksonxly profile image
Jackson Ly •

BRAVO, 3 runs out of 3, on Claude Code 2.1.328 with Opus 5.5, run headless in a fresh repo. The string ALPHA appears nowhere in the session transcript, while CLAUDE.md is attached as project instructions. Each run called the skill, CHARLIE came back in the tool result, and the answer was still BRAVO. A plugin I have installed also injects text at session start saying user instructions, CLAUDE.md and AGENTS.md included, take precedence over skills. I didn't run it without the plugin, so a bare install may answer differently.

Collapse
 
debashish_ghosal profile image
Debashish Ghosal •

This is the most useful receipt in the thread, thank you for running it and for stating the version. The plugin is the variable I would want isolated: it injects a precedence rule at session start, so your BRAVO may be the plugin's policy rather than the harness default. That distinction matters for exactly the reason the piece argues, because teams will read "BRAVO won" as a harness fact when it might be a plugin fact. If you ever re-run without the plugin, I would love the letter and the version, and I will note that the result is only comparable at the same plugin set.

Collapse
 
innokentyb profile image
Kent Bodrov •

I’d add a second check beyond which instruction wins: whether the boundary is enforced when the agent chooses a tool. A sentinel answer tells us what appeared in the response; a draft-only task with a mocked publish tool tells us whether the agent actually attempts the forbidden action. I’d keep the harness version and enabled plugins with both results. Has anyone seen those two checks disagree?

Collapse
 
debashish_ghosal profile image
Debashish Ghosal •

Yes, and they disagree often, which is the whole reason your second check is the better one. The sentinel letter tests what ended up in the prompt and the response. The mocked-tool test tests what the agent actually does when it has a reason to cross the line. I saw this exact split while field-testing a policy gate: the agent refused every destructive action, which looked like compliance, and then I traced it and found my policy hook had never loaded. The refusals were the harness's own defaults. The sentinel would have said "compliant." The mocked-tool probe would have said "your gate is not in the loop." Run both, and keep the harness version and the plugin list next to the result, exactly as you suggested.

Collapse
 
mousap_ali_5fbb6ff0019df2 profile image
mousap ali •

The missing referee is the key point, and I'd take it one step further: instruction files are preferences, so anything that must hold shouldn't live in them at all. Move hard rules into config the harness enforces whatever the model reads: requirements.toml set by an admin for Codex, managed settings and hooks for Claude Code, enterprise hooks.json for Cursor. Then a conflict between AGENTS.md, CLAUDE.md and a skill can change style or workflow, but not whether the agent may push to main or read .env.
Disclosure: I work on SecGuardRail (secguardrail.com), which checks each Codex, Claude Code and Cursor action before it runs.

Collapse
 
debashish_ghosal profile image
Debashish Ghosal •

This is the cleanest formulation of the fix in the thread, and it sharpens my own: the canonical file handles preferences, and the harness handles constraints. "May not push to main" and "may not read .env" are not preferences that need a tie-break rule, they are invariants that should be enforced regardless of what any instruction file says. That reframes the conflict demo: the interesting question is not only which file wins, it is which of your rules are living in the file layer at all when they should be in the enforced layer. Thanks for the disclosure, the harness-enforced pattern is the right target.

Collapse
 
prascli profile image
Indra Prasetya •

One concealment vector we measured in agent instruction files: a single line can hide a second instruction behind 150 or more spaces, tabs, or Unicode space separators (U+00A0, U+3000). Editors without soft wrap and PR diff views show only the text before the gap, while the agent reads the whole line.

cfgaudit's CFG137 (PR #1758, merged 14 Nov 2026, 5 files, 237 lines) flags it: counts runes not bytes, skips fenced code blocks and Markdown tables, exits 1 under --strict. It does not catch 149 blanks or zero-width/RTL tricks, which need separate rules.

Same gap between what a human skims and what a machine reads, so conflicting instructions can be hidden rather than just disagreed about.

Collapse
 
debashish_ghosal profile image
Debashish Ghosal •

This is a real and underappreciated cousin of the conflict problem, and it deserves its own name. A conflict is two rules that disagree in the open. This is one rule hiding behind whitespace, which is worse, because the human review that is supposed to catch conflicts is exactly the layer the concealment defeats. Same root as the piece's thesis: the gap between what a human skims and what the machine reads. Counting runes not bytes is the right call, and you are right that the boundary cases (149 blanks, zero-width, RTL) need separate rules rather than a looser threshold. A bounds check on rendered text before review is a good default for any instruction-file linter.

Collapse
 
alexshev profile image
Alex Shev •

A precedence rule is not enough unless conflicts are observable. I would give every instruction a scope, source, and priority, then make the agent surface the exact conflict before it acts when two applicable rules disagree. Silent “best effort” resolution is how local policy gets overridden without anyone noticing.

Collapse
 
max_quimby profile image
Max Quimby •

The "no referee, fails silently" framing is the real sting here. In our setup the resolution order isn't even stable within one harness — it drifts the moment someone edits a skill file that ships with a marketplace plugin and nobody re-runs the conflict check. What helped was to stop treating the three sources as peers and declare an explicit precedence in one place, then write a tiny startup probe that injects exactly your ALPHA/BRAVO/CHARLIE sentinel and logs which letter comes back on every agent boot. That turned an invisible policy conflict into a line in the startup log we can diff across versions — cheap insurance.

One question back: when you ran the demo, did the losing instructions get silently dropped, or did the model try to reconcile them — answer "ALPHA" but mention BRAVO in passing? We've seen both, and the reconciliation case scares me more, because it looks like partial compliance instead of a clean loss, so you don't even get a clear letter to act on.

Collapse
 
debashish_ghosal profile image
Debashish Ghosal •

Both, and the reconciliation case is the one that should scare you, which I think you already suspect. Sometimes the losing rule is dropped cleanly and you get a clean letter. Sometimes the model answers ALPHA but mentions BRAVO in passing, which is partial compliance dressed as agreement, and it gives you no clean signal to act on. The startup probe is a genuinely good idea: logging the sentinel letter on every boot turns a silent policy conflict into a diffable line, and it catches the drift you described when a marketplace plugin updates a skill underneath you. I would add the plugin set and version to that log line, since your own case shows the plugin can be the thing setting the precedence.

Collapse
 
prascli profile image
Indra Prasetya •

One concrete failure mode I'd add to your audit: instruction files can carry text hidden behind long runs of blanks that renders invisible in most editors but is still read by the agent. We caught this in our own scanner (CFG137): a single long-blank line can hide a full paragraph. Second: a repo that keeps one rule file and symlinks the other name to it gets audited twice, the always-on token total doubles, and the grade drops a band. Canonical-plus-references fixes both, but only if you also check for symlinked instruction files and run a bounds check on rendered text before review. Run the three-letter demo too, but measure the file, not just the letter.

Collapse
 
debashish_ghosal profile image
Debashish Ghosal •

The symlink double-count is a good catch and a genuinely new failure mode for the audit: two names, one file, counted twice, and the always-on cost silently doubles while the content did not. Canonical-plus-references does fix it, but your qualifier is the important part: only if the audit resolves symlinks before counting. And "measure the file, not just the letter" is the right closing instruction, because the letter tells you which rule won, and the file tells you how much context you are paying for on every single turn.

Collapse
 
alexcodebytes profile image
Oleksandr •

Love the ALPHA/BRAVO/CHARLIE canary test—stealing this for our repo setup.
One extra layer of chaos I've noticed: even when the harness has a deterministic loading order, the LLM itself acts as a soft referee. When AGENTS.md and a third-party skill both end up in the system prompt with conflicting instructions, the model doesn't always pick a clean winner—sometimes it blends them, hallucinates a compromise, or flips based on which instruction sits closer to the end of the context window (recency bias).
Treating AGENTS.md as the single canonical source and turning CLAUDE.md into a thin pointer is honestly the only sane way to keep diffs reviewable.

Collapse
 
debashish_ghosal profile image
Debashish Ghosal •

The model as a soft referee is the layer that no documentation covers, and it is why the demo result is not stable across harnesses or versions. Even with a fixed loading order, the resolution can be a blend or a recency-biased flip, which means the "winner" is a property of the prompt construction, not a policy anyone wrote. That is the argument for canonical-plus-pointers taken one step further: if there is only one rule text, there is nothing to blend and nothing to bias toward. Thanks for the canary-test note, I would love to hear what letter your setup returns after the next harness bump.

Collapse
 
robertpaschal profile image
Odinaka Robert Nnamani •

one file as the source of truth and the rest as pointers is the cleanest version of this. otherwise the newest file quietly wins.

Collapse
 
debashish_ghosal profile image
Debashish Ghosal •

"Otherwise the newest file quietly wins" is the failure stated better than I did. It is the same property that makes config drift dangerous: whichever file was edited most recently becomes the effective policy, and nobody decided that, it just happened. Pointers fix it because a pointer cannot restate a rule, and a rule that cannot be restated cannot drift. The one thing to watch is the pointer itself going stale (pointing at a section that moved), which is why the pointer should be a link to the canonical file, not a paraphrase of it.

Collapse
 
robertpaschal profile image
Odinaka Robert Nnamani •

Stealing that line. The newest file quietly winning is the whole failure in one sentence.