rules-doctor 0.3: Check If Your CLAUDE.md Is "Deceiving" Your AI Agent

AI coding agents increasingly rely on rule files like CLAUDE.md, .cursorrules, and AGENTS.md to govern their behavior. But there's an overlooked question: are these rule files themselves reliable? The open-source tool rules-doctor version 0.3 poses a sharp challenge — is your rule file actually worth loading?

From "Can Be Loaded" to "Worth Loading"

rules-doctor's evolution has been deliberate. v0.1 addressed the most fundamental issues: whether rule files could be correctly loaded — detecting broken @import references, shadowed AGENTS.md files, and instruction bloat. v0.2 strengthened import analysis. With v0.3.0, the tool's focus shifts from "technically loadable" to the harder question of "is the content actually valuable?"

This shift is grounded in real community pain points. Two recurring complaints dominate developer discussions: scope creep — agents modifying files nobody asked them to touch — and unreliable rule files — instructions written in CLAUDE.md or .cursorrules that get quietly ignored mid-task. A Hacker News post scoring 219 points, titled "Agents don't need memory, they need documentation," reinforces this from another angle: if documentation is the system, then documentation must be trustworthy.

A shadowed AGENTS.md occurs when multiple same-named rule files exist at different directory levels — a file in a subdirectory may override or block the parent-level file due to path resolution order, causing the developer's intended rules to never actually be read. Instruction bloat describes rule files that accumulate content over time without cleanup, eventually exceeding the model's effective context window range, or causing the model's compliance with later instructions to drop significantly due to excessive length — a direct manifestation of LLM "attention dilution" at the rules layer. Both are classic examples of "technically loadable but effectively broken," which formed the core focus of earlier rules-doctor versions.

What v0.3 Actually Checks

rules-doctor 0.3 introduces four checks targeting rule quality rather than syntax:

Check	Severity	What It Catches
CONTRADICTORY_RULES	error	Contradictory instructions in the same file, like "always run the full test suite" alongside "never run the full test suite." Faced with a conflict, the model picks one and quietly discards the other mid-task.
SCOPE_BOUNDARY_MISSING	warning	The file never declares which files/directories the agent is allowed to touch. Without an explicit scope, "don't overstep" isn't a rule an agent can follow — a static proxy indicator for scope creep risk.
VAGUE_DIRECTIVE	warning	Ambiguous phrasing like "as needed," "remember to," or "when appropriate." These read like suggestions, not rules — they're effectively unenforceable and are usually the first things dropped mid-task.
ADR_MISSING	warning	Non-trivial projects lacking Architecture Decision Records (ADRs). Decisions made in one session get re-litigated or quietly reversed in the next.

Usage is straightforward — one pip install, one command:

pip install rules-doctor
rules-doctor ~/my-project

The output is refreshingly direct, pointing out contradictions and suggesting fixes:

[ERROR] CONTRADICTORY_RULES -- CLAUDE.md
  Line 3 contradicts line 4 in CLAUDE.md: 'Always run the full test
  suite after changing code.' vs 'Never run the full test suite --
  it is too slow.'...
  Fix: Decide which rule wins, then delete or rewrite the loser.

The design philosophy is worth noting: contradictory rules are flagged as errors because they directly cause non-deterministic behavior, while missing scope, vague directives, and missing ADRs are warnings — the "eventually this will bite you" category.

Architecture Decision Records (ADRs) are structured documents in software engineering that capture important technical decisions along with their context, tradeoffs, and conclusions — typically stored as Markdown files in a repository (e.g., a docs/decisions/ directory). In AI agent workflows, missing ADRs create a specific problem: each new session starts without persistent cross-session memory. If the rule file doesn't record "why we chose approach A over approach B," the agent may re-evaluate and silently reverse architectural choices that were already settled in a previous session. Including ADR presence as a rule quality check essentially elevates "decision traceability" to a prerequisite for agent reliability.

Cost vs. Quality: Two Complementary Dimensions

The author carefully distinguishes rules-doctor from a similarly-minded tool, claude-code-guardrails. The latter's /cleanup-docs skill audits documentation from a cost perspective: measure → validate → trim, reporting in bytes — telling you how "expensive" your rules are (i.e., how much context they consume).

rules-doctor focuses on quality. The author's argument is sharp: a cheap rule file that contradicts itself, never declares scope, and is full of vague directives will still burn you mid-task — it just "fails cheaply." The two are complementary: use rules-doctor to make your rules trustworthy, then use cost auditing to make them lean.

This distinction highlights a commonly conflated problem. Many teams optimizing their CLAUDE.md focus solely on token consumption, working hard to compress the file shorter — while ignoring that compression alone does nothing to fix conflicting rules or ambiguous instructions. Short and wrong is more dangerous than long and right.

The cost perspective represented by claude-code-guardrails targets actual context window consumption in LLM calls. Every time an agent is invoked, the entire rule file is injected as a system prompt or context, directly increasing per-request token usage and affecting latency and cost. For frequently-called CI/CD pipelines or long-session tasks, bloated rule files can accumulate significant costs. That's precisely why "cost audit" tools exist — but as the article notes, compressing token count and improving instruction quality are orthogonal goals that need to be addressed separately.

Honest Limitations

The author maintains rare candor about the tool's boundaries. These checks are fundamentally text heuristics, not models. Contradiction detection works by matching instructions with opposite polarity on the same topic, so it will miss subtler conflicts and may produce false positives when referencing examples. Scope detection only recognizes explicit scope-declaration language.

When a check result looks suspicious, the author recommends validating against real Claude Code behavior — the --debug flag shows what was actually loaded. This "don't just trust my tool, go verify the truth" attitude paradoxically strengthens the tool's credibility.

From an engineering standpoint, rules-doctor has two additional advantages: zero dependencies, pure standard library implementation, and an MIT license. This means it can be integrated into virtually any CI pipeline as a quality gate for rule files with almost zero overhead.

Implications for AI Collaborative Workflows

rules-doctor's value extends beyond being a small utility — it reflects a critical insight in the maturation of AI-assisted programming: rule files are becoming first-class citizens that need to be engineered and managed as such. As we encode more behavioral constraints into CLAUDE.md, these files evolve from "casually written notes" into "configurations whose correctness must be guaranteed."

Traditional software engineering has long had linters, static analysis, and CI gates to ensure code quality — but quality assurance tooling for AI rule files is just getting started. rules-doctor transplants the linting mindset to the prompt/rules layer: contradiction detection, scope declaration, directive clarity — these checks map directly onto common issues in code review. As agentic workflows become mainstream, "rule linters" like this will likely become standard equipment.

As the author puts it: run it on your own CLAUDE.md — you probably won't like what it finds.