Your CLAUDE.md and AGENTS.md Are Quietly Conflicting and You Haven't Noticed

Title

Your CLAUDE.md and AGENTS.md Are Quietly Conflicting and You Haven't Noticed

Meta Description

AI coding tool config file fragmentation leads to drift and conflicts across CLAUDE.md, AGENTS.md, and more. Open-source tool ruleherd audits seven categories of issues: conflicts, dead references, stale info, and more. Zero dependencies, CI-ready.

Article Content

The fragmentation of configuration files for AI coding agent tools is becoming a hidden pain point in developers' daily maintenance. Claude Code uses CLAUDE.md, Codex and 30+ other tools use AGENTS.md, Cursor uses .cursor/rules, plus there's .windsurfrules, GEMINI.md, copilot-instructions.md… Write a single rule once and you have to paste it into five places. Six months later, these files start contradicting each other: one says use npm, another says use pnpm; one says never push to main, another says go ahead and push.

Developer princejain756 has open-sourced ruleherd on GitHub—a linter specifically designed to audit whether these instruction files have drifted. Its positioning is clear: no migration, just a health check.

Why Your Agent Config Will Definitely Drift

The root of the problem is the lack of a unified configuration standard in the AI coding tool ecosystem. Every tool wants its own config file, with different formats, different loading logic, and different scopes. The author's real experience is telling: he manually maintained a "universal rules file" and then manually synced it to five tool locations—and it still drifted.

The consequences of this drift go beyond mere "file inconsistency." When CLAUDE.md says use pnpm while AGENTS.md says use npm, different agent tools give contradictory recommendations. When a .mdc rule file's glob points to a deleted directory, Cursor silently ignores it—you think a rule is active when it was never loaded at all.

Existing sync solutions like rulesync can solve the problem, but at the cost of requiring you to adopt a new "single source of truth" format. For projects that have already accumulated multiple config files, this migration cost is often prohibitive.

What ruleherd Can Detect: A Look at Seven Issue Categories

ruleherd's core value is that it audits your existing files directly, with no format migration required. Run npx ruleherd to scan all instruction files in your repo and report seven categories of issues:

CONFLICT: Contradictions between files, such as tabs vs. spaces for indentation, npm vs. pnpm for package management, or "never" vs. "always" on shared topics.

DEAD REF: Backtick-wrapped paths and @imports pointing to non-existent files.

DEAD CMD: npm run x where x can't be found in package.json.

STALE: Rules that say "react 17" when package.json actually has react 19 installed.

DEAD GLOB: .mdc rule globs pointing to deleted directories—Cursor will silently never load them.

DUPLICATE: The same block of text pasted across multiple files.

BLOAT: Individual files exceeding ~4k tokens, loaded into the prompt every time and wasting context window.

It produces a percentage-based score, with non-zero exit in strict mode for CI. Zero dependencies, MIT license.

Running It in the Real World: A B-Grade

When the author ran ruleherd on his own machine (it also scans global configs), the output was quite convincing:

GRADE: B (85/100)
9 instruction files · ~4,757 tokens of agent context
  DUPLICATE ~333-char block in 6 files
  DUPLICATE ~939-char block in 6 files
  DUPLICATE ~705-char block in 6 files
          ~/.claude/CLAUDE.md, ~/.gemini/GEMINI.md,
          ~/.config/devin/AGENTS.md, windsurf global rules,
          ~/.agents/rules/, ~/.cursor/rules/browser-tooling.mdc

9 instruction files, ~4,757 tokens of agent context, and three duplicate blocks each appearing in 6 files. Even the author's manually maintained "universal rules" weren't spared—he had manually synced them, and they still drifted.

The Audit Tool's Own Limitations and Honesty

The author maintains a rare level of candor in the tool's documentation. Contradiction detection is heuristic—based on keyword pairing and never/always polarity, not semantic understanding. This means it may miss subtle contradictions, or false-positive on cases where wording differs but meaning is the same.

Dead reference checking is deliberately conservative, preferring to miss issues rather than false-positive. The author shares a telling detail: the first version of ruleherd flagged his @types/node as a dead file reference and pnpm install as a missing npm script—and both were in his own config files. Auditing the audit tool itself is indeed humbling.

A "clean" score from the tool only means "no drift detected," not "your rules are well-written." That distinction matters.

The Infrastructure Gap in the Multi-Config-File Era

ruleherd reflects a bigger problem: AI coding tools are going through a "Tower of Babel" phase for configuration files. Every new tool that enters the scene brings a new config file format, and developers are forced to become format converters.

In the short term, audit tools like ruleherd are a pragmatic stopgap—they don't ask you to change the status quo, just help you discover problems that already exist. It's well-suited for CI pipelines, checking config drift on every commit.

Long term, this problem may need an industry-level standard to solve. But until that standard emerges, making sure your CLAUDE.md and AGENTS.md aren't contradicting each other behind your back is the first thing every developer using multi-agent tools should do.

One-line Summary

ruleherd is an open-source linter that audits drift across multiple AI agent config files, detecting seven issue categories with no format migration required.

Paragraph Summary

The AI coding agent tool ecosystem lacks a unified configuration standard—Claude Code, Codex, Cursor, and others each use their own instruction files (CLAUDE.md, AGENTS.md, .cursor/rules, etc.), the same rule must be pasted in multiple places, and six months later drift and conflicts are inevitable. Author princejain756 has open-sourced ruleherd—a zero-dependency audit linter that doesn't migrate but health-checks, detecting seven categories of issues: conflicts, dead references, dead commands, stale info, dead globs, duplicates, and file bloat, with a percentage-based score. The author ran it on his own machine and got a B-grade (85/100), finding 9 instruction files with multiple duplicate blocks and ~4,757 tokens of wasted agent context. The author candidly notes that contradiction detection is heuristic rather than semantic, with possible false negatives and positives. The tool is well-suited for CI pipelines to periodically check config drift.