DEV Community

Jessy Brenenstahl
Jessy Brenenstahl

Posted on

Your AI coding agents are reading conflicting instructions

#ai #claude #devops #productivity

Run Claude Code, Codex and Cursor on the same repo for a week and you'll end up with a CLAUDE.md, an AGENTS.md, a .cursor/rules folder and a README that each say something slightly different. One says "use pnpm", another says "npm is fine". One says "never touch migrations", another has a migration workflow.

Agents don't flag these conflicts. They just follow whichever rule they read last, or whichever one is closest to the task. So you get behavior that changes depending on which tool you opened that morning.

Step 1: find every instruction file 

find . -maxdepth 4 \( -name 'CLAUDE.md' -o -name 'AGENTS.md' -o -name '.cursorrules' \
  -o -path '*/.cursor/rules/*' -o -name 'GEMINI.md' -o -name 'RULES.md' \) -not -path '*/node_modules/*'
ls ~/.claude/CLAUDE.md ~/.codex/AGENTS.md 2>/dev/null   # global files follow you into every repo
Enter fullscreen mode Exit fullscreen mode

Global home-dir files are the sneaky ones. They're applied to every project and quietly override project facts.

Step 2: list the contradictions

Go through the files topic by topic: package manager, test command, branch/commit rules, what counts as "done", forbidden directories. Write each conflict down as "File A says X, file B says Y".

Step 3: declare a precedence order, and tell the agents

When two rules disagree, the higher one wins:

  1. The live human message in the current session
  2. Safety rules (no force-push, no secrets, no deleting outside the repo). Never overridden by anything lower.
  3. The nearest scoped file (sub/dir/RULES.md beats root for files under sub/dir)
  4. The canonical root RULES.md
  5. Agent-specific pointer files (CLAUDE.md, AGENTS.md, .cursor/rules), for tool quirks only
  6. Global home-dir files, for personal defaults only
  7. README / docs prose: background, not instructions

Paste this at the top of your canonical file:

Precedence: the user's current message > Safety section below > the nearest RULES.md in the directory tree > this file > agent-specific files > global defaults. If two rules conflict and this order doesn't settle it, stop and ask. Don't pick one.

That last sentence matters most. "Stop and ask" turns a silent wrong guess into a visible question.

Step 4: one source, thin pointers

Put the real rules in one RULES.md. Make CLAUDE.md and AGENTS.md a few lines each: "Read RULES.md first. Tool-specific notes: ..." Now there's only one place to edit, and the agents can't drift apart.

Step 5: log decisions

Keep a short conflict log ("2026-10-12: pnpm wins, npm lines removed from AGENTS.md"). Without it, an agent will happily reintroduce the rule you deleted last week because it found it in an old commit message.

The free audit checklist is on GitHub: agent-ops-samples.
If you want the full set (precedence model, single-source templates for RULES.md / CLAUDE.md / AGENTS.md / Cursor, conflict log), it's the Agent Instructions Conflict Kit ($9).

Top comments (0)