Claude Rules Doctor

Catch dead Claude rules before they silently do nothing.

[](https://github.com/hesreallyhim/awesome-claude-code)

🩺 claude-rules-doctor

CLI that verifies `.claude/rules/*.md` `paths:` globs actually match files in your project.

Quickstart

# One-off
npx claude-rules-doctor check --root .

# Or install globally
npm install -g claude-rules-doctor
rules-doctor check --root .

Problem

Claude rules with `paths:` frontmatter can silently fail if:

undefined

This tool scans all your rules and tells you which ones are "dead" (not applying to any files).

Usage

Check current project

rules-doctor check

CI mode (exit 1 if dead rules found)

rules-doctor check --ci

JSON output

rules-doctor check --json

Verbose mode (show matched files)

rules-doctor check --verbose

Check specific directory

rules-doctor check --root /path/to/project

Output

undefined

WARNING triggers

A rule gets WARNING status when:

undefined

Example output (test-suite/6-mixed)

$ rules-doctor check

🔍 Rules Doctor - Check Results

✅ OK      /.claude/rules/valid.md
  Matches 1 file(s)

✅ OK      /.claude/rules/global.md
  Global rule (no paths specified)

❌ DEAD    /.claude/rules/dead.md
  No files match the specified paths

Summary:
  Total rules: 3
  ✅ OK: 2
  ⚠️  WARNING: 0
  ❌ DEAD: 1

⚠️  Found 1 dead rule(s). These rules won't apply to any files.

CI (GitHub Actions)

...