Audit .claude/rules/ files for structural correctness, glob validity, and real-world usefulness. Resolves each paths: pattern against actual project files, then asks the user whether each rule is still relevant and useful. Can update rules in-place based on answers. Use when setting up rules for the first time, debugging rules that fire too often or never, or doing a periodic rules hygiene pass.
Discover all rule files, validate their structure and glob patterns against the real project, then run an interactive session to confirm (or improve) each rule with the user.
The goal is not just to score — it is to leave the rules directory in better shape than it was.
.claude/rules/ files (validate before committing)@ imports from CLAUDE.md to path-scoped rules| Mechanism | When it loads | Notes |
|---|---|---|
@file in CLAUDE.md | Session start, always | Even inside a conditional sentence |
| No in rule |
paths:| Session start, always |
| Same cost as @import |
paths: frontmatter | When Claude reads a matching file | Trigger = Read tool, not Write |
The paths: field is the main lever for keeping rules contextual. An always-on rule with 80 lines loads on every session even if you're fixing a typo in README.md.
| # | Criterion | Max | What is checked |
|---|---|---|---|
| 1 | frontmatter block | 1 | File has YAML frontmatter (--- delimited) |
| 2 | paths: field | 2 | Present (1pt) + at least one pattern listed (1pt) |
| 3 | pattern validity | 3 | Each pattern matches ≥1 file in project (up to 3 patterns checked) |
| 4 | scope | 2 | Not dead (≥1 match) + not too broad (<30% of project source files) |
| 5 | content quality | 3 | Has clear header/title (1pt) + rules are specific/actionable (1pt) + under 150 lines (1pt) |
| Bonus | focus | +1 | Under 15 rules in file |
Thresholds:
Always-on rules (no paths: field): skip criteria 2, 3, 4. Score on 5 pts max. Flag with 🔵 and go through the interactive step to decide if scoping is needed.
Use Glob to find all rule files:
.claude/rules/**/*.md
If an argument was passed (e.g., /eval-rules ./my-rules/), use that path instead.
Also count total source files for scope % calculation:
find . \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \) \
! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/dist/*" \
2>/dev/null | wc -l
If no .claude/rules/ directory exists, report it and stop.
For each .md file found:
--- and second ---)paths: field — collect all glob patterns as a listpaths:) or always-on (no frontmatter or no paths:)For each rule with paths:, use Glob to resolve each pattern against the project:
Process rules one by one. Do not batch and skip the interaction.
For each conditional rule (has paths:):
Show:
Rule: payments.md [conditional]