Your CLAUDE.md Might Not Be Loading — I Built a Check-Up for That

Description and use

rules‑doctor statically analyzes Claude Code rule files to detect import, shadowing, and bloat issues, providing fixes and a compliance score.

Problem

Rule files for Claude Code may silently fail to load due to import placement, shadowing of AGENTS.md, or file size limits, causing expected behavior to be ignored.

Outcome

rules-doctor identifies and reports import expansion failures, AGENTS.md shadowing, and rule file bloat, enabling developers to correct rule files and achieve a higher compliance score.

Workflow

• Install rules-doctor via pip
• Run rules-doctor on the project directory
• Review the report for errors, warnings, and suggestions
• Apply suggested fixes to rule files
• Re-run rules-doctor to confirm resolution
• Integrate --fail-on error flag into CI to enforce rule hygiene

Evidence

Three ways rule files silently fail

Source

I built rules-doctor: a tiny zero-dependency Python CLI that statically simulates Claude Code's rule-loading pipeline and gives your project a check-up.

Source

Every finding comes with a concrete fix suggestion, and you get a 0–100 score with a letter grade.

Source

This is a static heuristic simulation, not the Claude Code loader.

Source