florianbruniaux/claude-code-ultimate-guide/eval-rules

Rules evaluator

Discover every Claude Code rule file, validate its structure and paths globs against the real project, then review each rule with the user so the rules directory ends in better shape than it started.

This skill covers Claude Code instruction rules in .claude/rules/ and ~/.claude/rules/. It does not cover Codex .rules files, which are Starlark command-approval policies, not instructions. See "Codex" below.

When to use

• Writing .claude/rules/ files for the first time
• A rule never seems to apply, or applies to everything
• Moving @ imports from CLAUDE.md into path-scoped rules
• Periodic hygiene: are these rules still accurate and useful?
• After onboarding to a new codebase

Modes

When a ctxharness doctor --format json report generated during this task is available, every rules-layer finding it reports must appear in the audit. The doctor checks structure only; dead patterns, breadth and content are this skill's job.

Key concepts

• All .md files under .claude/rules/ are discovered recursively.
• paths is the only frontmatter field Claude Code reads from a rule; other fields are ignored without an error. It accepts a YAML list or a comma-separated string. Fields from other tools' rule formats, such as Cursor's globs, alwaysApply or description, are therefore ignored too: a rule scoped with globs: silently loads always-on.
• If the frontmatter YAML does not parse, Claude Code ignores the frontmatter and loads the rule as if it had no paths, so a broken scoped rule silently becomes always-on.
• Brace expansion works ("src/**/*.{ts,tsx}"). A rule's whole paths list shares a budget of 1,000 expanded patterns and 4 MiB; a pattern over budget is used unexpanded and its literal braces match nothing.
• A [ that cannot be read as a bracket expression (for example photos [2024/**) makes that pattern invalid: it matches nothing, the other patterns still work. Escape a literal bracket as \[.
• Project rules are skipped when project is excluded from --setting-sources.
• User rules load before project rules; neither overrides the other, so a conflict between them is a defect to resolve.

Symlinked rules

• A symlink whose target is inside the working directory loads normally.
• A symlink whose target is outside the working directory is treated like an external import: it does not load until external imports are approved for the project, and after approval only the linked rules without paths load.
• A symlink to a network path (UNC share, /net, /Network) never loads. \\wsl$ paths are not network paths.
• Circular symlinks are detected and handled.
• The memory documentation says the approval prompt appears only for @path imports, but the v2.1.284 changelog reads: "Fixed rules symlinked into .claude/rules from outside the project being skipped without ever showing the external-imports approval prompt". From v2.1.284, an external symlinked rule asks for the same approval; on older versions it is skipped silently. Check the running version before reporting the load status.

To share rules across projects without approval, put them in ~/.claude/rules/.

Scoring Criteria (12 pts per scoped rule)

Always-on rules (no paths): score criteria 1 and 5 only (4 pts, plus bonus), mark them always-on, and decide in the interactive step whether they should be scoped.

User rules (~/.claude/rules/): their patterns resolve against whichever project is open, so criteria 3 and 4 are N/A in a user-level audit. Score them only when auditing a named project.

Symlinked rules: add a load-status note (loads, needs external-import approval, loads only after approval and only if unscoped, never loads: network path). A rule that cannot load gets status Fix regardless of score.

Thresholds: Good >= 83%, Needs work 58-82%, Fix < 58%.

Execution instructions

Step 1: Discovery

Find rule files with the file search capability:

.claude/rules/**/*.md

If an argument names another path, use it. Include ~/.claude/rules/ when the user asks for the full picture.

Count project files for the scope percentage from what the repository actually contains, not a fixed list of extensions:

git ls-files --cached --others --exclude-standard | wc -l   # inside a git repository

Outside git, count files while excluding .git, node_modules, build output and other ignored directories.

Claude Code matches paths against the files Claude reads, tracked or not. Resolve patterns in Step 3 against the files on disk (excluding .git and node_modules), not against git ls-files alone, or a pattern that targets a gitignored directory looks dead when it is not.

Check whether the rules directory is shared with the team: git check-ignore -v .claude/rules/<file> or git ls-files .claude/rules | wc -l. Report a gitignored or untracked rules directory as local-only: those rules apply on this machine and nowhere else.

For every symlink in the rules tree, record the resolved target and whether it is inside the working directory or a network path.

Done when: every rule file is listed with its location (project or user), symlink status and tracking status, and the project file count is recorded. If no rules directory exists, report it and stop.

Step 2: Parse each rule

For each file: read it in full, extract the frontmatter, normalize paths (list or comma-separated string) into a list, classify the rule as scoped or always-on, and note parse errors, unknown fields (ignored by Claude Code), line count, and title. A globs field without paths is a finding of its own: the author meant to scope the rule, but it loads always-on; propose renaming the field to paths.

Done when: every rule has a classification and a parse status.

Step 3: Resolve patterns

For each pattern, resolve it against the project files. Record the match count, up to 10 sample paths, and flag dead patterns, invalid [ patterns, patterns whose brace expansion exceeds the budget, and rules whose pattern union matches more than 30% of the counted files. This resolver lists tracked and untracked files from git, then also walks a gitignored directory when a pattern's literal prefix points into it, so .claude/rules/** is not reported dead in a repository that ignores its rules. It expands braces and treats **/ as zero or more directories; dotfiles match. The exact matcher Claude Code uses is not documented, so report a borderline result as such. Pass one rule's patterns per run:

python3 - "$PROJECT_ROOT" "src/**/*.{ts,tsx}" "prisma/**" <<'EOF'
import os, re, subprocess, sys
root, patterns = sys.argv[1], sys.argv[2:]
def braces(p):
    m = re.search(r"\{([^{}]*)\}", p)
    return [q for alt in m.group(1).split(",") for q in braces(p[:m.start()] + alt + p[m.end():])] if m else [p]
def regex(p):
    out, i = "", 0
    while i < len(p):
        if p.startswith("**/", i): out, i = out + "(?:.*/)?", i + 3
        elif p.startswith("**", i): out, i = out + ".*", i + 2
        elif p[i] == "*": out, i = out + "[^/]*", i + 1
        elif p[i] == "?": out, i = out + "[^/]", i + 1
        else: out, i = out + re.escape(p[i]), i + 1
    return re.compile(out + r"\Z")
def walk(top):
    for d, ds, fs in os.walk(os.path.join(root, top)):
        ds[:] = [x for x in ds if x not in {".git", "node_modules"}]
        yield from (os.path.relpath(os.path.join(d, f), root) for f in fs)
git = subprocess.run(["git", "-C", root, "ls-files", "-co", "--exclude-standard"], capture_output=True, text=True)
files = set(git.stdout.splitlines()) if git.returncode == 0 else set(walk(""))
base = len(files)
for p in patterns:
    prefix = re.split(r"[*?\[{]", p)[0].rsplit("/", 1)[0] if "/" in p else ""
    if prefix and git.returncode == 0 and subprocess.run(["git", "-C", root, "check-ignore", "-q", prefix]).returncode == 0:
        files |= set(walk(prefix))
union = set()
for p in patterns:
    hits = {f for f in files if any(regex(q).match(f) for q in braces(p))}
    union |= hits
    print(f"{len(hits):6d}  {p}  {sorted(hits)[:3]}")
print(f"union {len(union)} of {base} project files ({100 * len(union) / max(base, 1):.1f}%)")
EOF

Done when: every pattern has a match count and a flag list.

Step 4: Interactive review

Process rules one by one.

For a scoped rule, show the file, its patterns, match count and samples, then ask:

1. Is this scope right? (y / adjust)
2. Is this rule still useful day to day? (y / n / unsure)
3. Anything to add, remove or update in the content? (describe / skip)

For an always-on rule, show the file and line count, then ask:

1. This rule loads every session. Keep it always-on, scope it, or skip? (keep / scope / skip)
2. Is the content still accurate and useful? (y / n)

If the user chooses scope, propose a paths block derived from the rule content and apply it only after confirmation. Apply other confirmed edits directly and confirm each one. An "unsure" answer is recorded as "review in next audit" with no edit.

Done when: every rule has a recorded answer (confirmed, edited, flagged stale, unsure, or skipped).

Step 5: Report

# Rules Audit: [project]
Date: [today] | Scanned: N rules (X scoped, Y always-on, Z symlinked)
 
| Status | Count |
|--------|-------|
| Good | N |
| Needs work | N |
| Fix | N |
| Always-on | N |
| Cannot load (symlink or network) | N |
| User confirmed useful | N |
| User flagged for update | N |
| User marked stale | N |
 
### payments.md (11/12) [scoped]
paths: `**/payments/**`, `src/billing/**`
Matches: 12 files (3.5% of 340 tracked files)
 
| Criterion | Score | Notes |
|---|---|---|
| frontmatter parses | 1/1 | ok |
| paths field | 2/2 | 2 patterns |
| pattern validity | 3/3 | all match |
| scope | 2/2 | well scoped |
| content quality | 2/3 | 158 lines |

End with a change summary: edits applied, rules flagged stale. Never delete a rule without an explicit "yes, delete it".

Done when: the report covers every rule found in Step 1.

Codex

Codex has no equivalent of .claude/rules/. When the request is about Codex: