v0.1 of rules-doctor
checked that your rule files load correctly: dead @imports, shadowed
AGENTS.md, instruction bloat. v0.2 hardened the import analysis.
v0.3.0 asks the harder question: are your rules worth loading at all?
Community pain research keeps surfacing the same two complaints as the
loudest, best-evidenced categories: scope creep (the agent edits files
nobody asked it to touch) and rule-file unreliability (CLAUDE.md /
.cursorrules instructions that get quietly ignored halfway through a task).
The HN thread "Agents don't need memory, they need documentation" (219 pts)
made the same point from the other side: the docs are the system — so they'd
better be trustworthy.
What v0.3 checks
| Check | Severity | What it catches |
|---|---|---|
CONTRADICTORY_RULES |
error | "Always run the test suite" vs "Never run the test suite" in the same file. A model faced with both picks one and silently drops the other mid-task. |
SCOPE_BOUNDARY_MISSING |
warning | The file never says which files/dirs the agent may touch. Without an explicit scope, "stay in your lane" isn't a rule the agent can follow — this is the static proxy for scope-creep risk. |
VAGUE_DIRECTIVE |
warning | Weasel phrasing — "as needed", "remember to", "when appropriate". Reads like guidance, unenforceable in practice, first thing dropped mid-task. |
ADR_MISSING |
warning | Non-trivial project, no Architecture Decision Records. Decisions made by one session get re-litigated — or silently reversed — by the next. |
pip install rules-doctor
rules-doctor ~/my-project
Example:
[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.'. A model faced with both picks one and silently
drops the other mid-task.
Fix: Decide which rule wins, then delete or rewrite the loser.
Cost vs quality
tillmeier/claude-code-guardrails's
/cleanup-docs skill audits docs by cost: measure → verify → cut,
reports in bytes. That tells you how expensive your rules are.
rules-doctor checks quality. 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
These are text heuristics, not a model. Contradiction detection matches
opposite-polarity directives on overlapping topics — it misses subtle
conflicts and can misfire on quoted examples. Scope detection looks for
explicit scope language. When a finding looks suspicious, verify against the
real Claude Code (--debug shows what was actually loaded).
Zero dependencies, pure stdlib. MIT.
- GitHub: https://github.com/hahahahahahahahah6/rules-doctor
- PyPI: https://pypi.org/project/rules-doctor/
Run it on your own CLAUDE.md — you might not like what it finds.
Top comments (0)