rules-doctor

A check-up for your CLAUDE.md / AGENTS.md rule files. It statically simulates how Claude Code loads project rules and reports the silent failures that waste your context window:

• Dead @imports — an @import written inside a fenced code block is rendered as literal text and never expanded. Neither is one pointing at a file that doesn't exist.
• Shadowed files — when CLAUDE.md and AGENTS.md sit in the same directory, only CLAUDE.md is loaded. Your AGENTS.md is silently ignored.
• Instruction bloat — past ~150 instruction lines, models start dropping or deprioritizing rules. rules-doctor tells you when you've crossed the line.
• v0.3 reliability lint — contradictory directives ("always X" vs "never X"), missing scope boundaries (the static proxy for scope creep), weasel phrasing models ignore mid-task ("as needed", "remember to"), and missing Architecture Decision Records in non-trivial projects.

Zero dependencies. Pure standard library.

Install

pip install rules-doctor

Usage

# Check the current project
rules-doctor

# Check another directory
rules-doctor ~/my-project

# CI mode: exit 1 if any errors (or warnings) are found
rules-doctor --fail-on error

# Compact output
rules-doctor --quiet

Example output:

rules-doctor report: /home/hao/my-project
Score: 70/100 (C)

Rule files found (2, 1 loaded):
  - CLAUDE.md [project root] -- PRIMARY -- loaded by Claude Code
  - AGENTS.md [project root] -- fallback -- loaded only if no CLAUDE.md nearby

Issues (2):

[ERROR] SHADOWED_AGENTS_MD -- AGENTS.md
  (project root): AGENTS.md is shadowed by CLAUDE.md -- when both exist,
  only CLAUDE.md is loaded and AGENTS.md is silently ignored.
  Fix: Keep a single source of truth: merge the AGENTS.md rules into
  CLAUDE.md (or vice versa) and delete the other file.

[WARN] DEAD_IMPORT -- CLAUDE.md
  Dead @import at CLAUDE.md:42: '@rules/deploy.md' sits inside a fenced
  code block, so it is rendered as literal text and never expanded.
  Fix: Move the import out of the code fence onto its own line, e.g.
  `@rules/deploy.md` with no surrounding backticks.

What it checks

Scoring: start at 100, −15 per error, −5 per warning, floor of 0. Grades: A ≥ 90, B ≥ 75, C ≥ 60, D ≥ 40, F < 40.

How it differs from cost-focused doc tools

tillmeier/claude-code-guardrails ships a /cleanup-docs skill that audits docs by cost: measure → verify → cut, token-greps every fact before removing text, reports in bytes. That tells you how expensive your rules are.

rules-doctor checks quality: whether the rules are worth loading at all. A cheap rule file that contradicts itself, never declares a scope boundary, or leans on weasel phrasing will still fail you mid-task — it just fails cheaply. The two are complementary: run rules-doctor first to make your rules trustworthy, then a cost audit to make them cheap.

Honest limitations

This tool is a static heuristic simulation, not the Claude Code loader. Anthropic does not publish the exact rule-loading algorithm, and it changes between versions. Concretely, this means:

• The shadowing model is inferred from observed behavior (e.g. reports that Claude Code ignores AGENTS.md when CLAUDE.md exists), not from official documentation. If Anthropic changes precedence, reports can be wrong in either direction — false alarms or missed shadows.
• @import semantics are approximated. The 4-hop nesting limit, fence handling, and inline-mention behavior are best-effort guesses. Edge cases (quoted paths, fragments like @file.md#section, symlinks) may be misclassified.
• Token counts are len(text) // 4, a rough rule of thumb for English prose. Code, URLs, and CJK text tokenize very differently.
• The ~150 instruction-line limit is a heuristic, not a measured cliff. Model attention degrades gradually; your mileage varies by model version.
• Only Markdown-style rule files are understood. .claude/ project config (settings, hooks, skills) is noted but not validated.
• v0.3 checks are text heuristics, not a model. Contradiction detection matches opposite-polarity directives on overlapping topics — it can miss subtle conflicts ("use pnpm" vs "use npm") and can misfire on quoted examples. Scope-boundary detection looks for explicit scope language; an unconventional-but-clear scope section may not match. ADR detection treats

  5 source files (or a conventional src/-style dir) as "non-trivial".

When a finding looks suspicious, verify against the real Claude Code (--debug shows what was actually loaded). Bug reports with a minimal repro are welcome — that's how the heuristics get better.

Development

pip install pytest
python -m pytest tests/ -q

License

MIT — see LICENSE.