Something useful dropped at agentlint.net last week. The story of why it exists will make you audit your own config before you finish reading this.
Most teams building with AI agents spend serious time on prompts, models, and tool integrations. Config file hygiene barely makes the list. You write a rules file early, maybe add a CLAUDE.md when you start a new project, reference a few hook configs, and move on. The assumption baked into all of it is that the agent reads everything and synthesizes a coherent understanding. That assumption is mostly true, right up until two files disagree with each other.
A dev was reviewing a PR and noticed lockfile conflicts everywhere. Half the dependencies installed with pnpm, half with bun. After 20 minutes of digging, the cause surfaced: their CLAUDE.md said “always use pnpm” while a separate rules file said “prefer bun for speed.” The agent saw both, picked whichever instruction was contextually closest to the task at hand, and kept moving. No warning. No flag. Zero indication anything was wrong. The build broke, the PR review ballooned from a five-minute check into a thirty-minute archaeology session, and the team had to manually reconcile lockfiles across packages before anything could merge.
That’s the twist. Agents don’t surface contradiction errors. They resolve conflicts silently by local proximity, and you only find out when the build breaks. Stale refs are the same problem in a different suit: rename a script, forget to update the hook that calls the old path, and the agent just silently does nothing. The work you think is happening isn’t happening. No error, no log, no signal. Because the agent moves on confidently, you usually don’t catch it until something downstream fails. Think about how many times you’ve gotten unexpected agent behavior and blamed the model when the real culprit was a rules file arguing with another rules file somewhere in your config layer.
So the dev built a linter for the whole surface. Agentlint is a GitHub app that audits all your agent config files on every PR. Not regex, because contradictions in natural language don’t parse cleanly with pattern matching. It runs a full LLM pass. It pulls every config file in scope, finds contradictions between them, and catches dead references before they derail a build. The output is structured enough to act on without being noisy enough to ignore.
How to use it (and tighten your setup while you’re at it):
- 🗂️ Map your config surface. List every file feeding instructions to your agent: CLAUDE.md, rules files, hook configs, workspace settings. If you don’t know what’s in scope, you can’t audit it. For most projects this list is longer than people expect. Don’t forget workspace-level settings, IDE integration files, and anything that sets environment defaults. A file you forgot to include is exactly the kind of file that silently overrides something important without any trace of having done it.
- 🔍 Pick one authoritative file. When two files can contradict each other, one of them has to win by design. Explicit hierarchy beats silent resolution every time. In practice this usually means one root-level config owns the global rules, and everything else is either an extension or a scoped override. Write that hierarchy down somewhere the agent can actually read it, not just somewhere a human would think to look.
- ⚡ Add override comments wherever you break the hierarchy. Something like
# overrides CLAUDE.md pnpm rule: use bun in /packages/web for build speedgives the agent real signal instead of a coin flip. The comment doesn’t need to be long. It just needs to exist so there’s no ambiguity about which instruction wins in that scope. Bonus: when you come back to that file six months later, you’ll understand the decision immediately without guessing at past context. - 🔄 Connect agentlint at agentlint.net. Takes about 30 seconds. It flags conflicts and dead refs on every PR going forward. Once it’s in your pipeline you can stop manually auditing config files during code review, because the tool catches the problems that are nearly impossible to spot by eye when you’re focused on actual code changes.
Pro tip: This isn’t a model bug you can prompt your way out of. Agents treat all instruction sources as roughly equal weight unless the hierarchy is explicit. One authoritative file with deliberate overrides is the fix, not tighter wording in the same contradicting files. Tightening the wording just makes each instruction more convincing on its own, which makes the conflict harder to detect, not easier. The root issue is architectural: two sources of truth in the same config layer. Fix the architecture first, then tune the wording if you still need to.
If your agent has ever done something unexpected without explaining why, your rules files might be arguing with each other. Worth finding out before the next PR. 🚀
Frequently Asked Questions
Q: Why did my agent pick one rule over another without asking?
Agents resolve conflicting instructions by local proximity , whichever rule they encounter last or closest to what they’re doing at the moment. This is a silent failure because they don’t flag the contradiction. The fix is to make one rule file authoritative and explicitly override others, so the agent has a clear priority.
Q: How do I set up a rule hierarchy to prevent conflicts?
Put your primary rules (like package manager choice) in your main CLAUDE.md or config file with explicit language like “Use pnpm for all projects unless explicitly overridden in writing.” Then, any subdirectory or context-specific overrides must reference the main rule and state why they’re different. This gives the agent a decision tree instead of a coin flip.
Q: What about stale file references that silently fail?
When you rename scripts or hooks, the agent won’t catch broken references , it just tries the old path and fails silently. Audit your entire config surface whenever you rename anything critical (or use a tool like agentlint.net). Some teams also run a simple grep check in CI to flag old script names in config files.
Q: How can I audit contradictions and dead refs automatically?
Tools like agentlint.net use LLM-based analysis (not just regex) to find contradictions and stale references across your config files. Run it on every PR to catch these issues before they cause silent failures. If you’re building your own solution, have the LLM pull all config files and look for inconsistencies and dead paths.
my agent switched package managers mid-PR because my rules files contradicted each other
by u/mm_cm_m_km in PromptEngineering