rules-auditor

name	rules-auditor
description	Audit Claude Code rules and CLAUDE.md/AGENTS.md files for staleness, quality, and drift. Use when asked to audit rules, check stale CLAUDE.md, check stale AGENTS.md, review rules freshness, assess rules quality, improve my rules, find dead globs in rules, check if rules are up to date, review progressive disclosure setup, find contradictory rules, or optimize Claude Code memory files.

Overview

This skill audits and improves Claude Code memory files — .claude/rules/*.md, CLAUDE.md, CLAUDE.local.md, and their AGENTS.md/AGENTS.local.md equivalents. AGENTS.md is a third-party alternative that uses the exact same rules, frontmatter, and progressive disclosure conventions as CLAUDE.md but with a different filename. This skill treats both identically.

Use this skill when asked to:

• Audit or review rules quality and freshness
• Find stale or broken rules
• Improve progressive disclosure setup
• Check if CLAUDE.md or AGENTS.md files are up to date
• Optimize Claude Code context loading

Discovery Workflow

Before auditing, discover all memory files in the project:

1. Find all rules files

find .claude/rules -name "*.md" -type f 2>/dev/null | sort

2. Find all CLAUDE.md and AGENTS.md files

find . \( -name "CLAUDE.md" -o -name "CLAUDE.local.md" -o -name "AGENTS.md" -o -name "AGENTS.local.md" \) | grep -v node_modules | grep -v .git | sort

Note: AGENTS.md is a third-party alternative to CLAUDE.md that uses the exact same format, frontmatter, and rules conventions. Treat AGENTS.md files identically to CLAUDE.md files throughout the audit.

3. Parse scoping from each rule

For each rule file, extract the paths: frontmatter to determine scope:

# Extract paths from YAML frontmatter
sed -n '/^---$/,/^---$/p' "$rule_file" | grep -A 50 '^paths:' | grep '^ *- ' | sed 's/^ *- *//'

• Global rules: No paths: frontmatter — loaded on every session
• Scoped rules: Have paths: with glob patterns — loaded only when Claude reads matching files

4. Build the inventory

Classify each file:

• Rule files with paths: → scoped rules (note the globs)
• Rule files without paths: → global rules
• Root CLAUDE.md or AGENTS.md → always loaded (ancestor of cwd)
• Nested CLAUDE.md/AGENTS.md files → loaded lazily when Claude reads files in that subtree

Audit Workflow

For each discovered memory file, perform these checks:

Step 1: Dead Glob Detection (scoped rules only)

For each glob pattern in paths:, verify files actually match:

# Test if a glob matches any files
shopt -s globstar nullglob
files=( $glob_pattern )
if [ ${#files[@]} -eq 0 ]; then
  echo "STALE: glob '$glob_pattern' matches no files"
fi

Common causes: directories renamed, file extensions changed, code moved to a different location.

Step 2: Referenced File Verification

Extract file paths mentioned in rule content and verify they exist:

# Find file references in rule content (paths like src/foo/bar.ts, ./config/x.json)
grep -oE '`[a-zA-Z0-9_./-]+\.[a-zA-Z]{1,5}`' "$rule_file" | tr -d '`' | while read -r ref; do
  [ ! -e "$ref" ] && echo "BROKEN REF: $ref in $rule_file"
done

Step 3: Code Pattern Verification

For key identifiers mentioned in rules (function names, class names, type names, command names):

1. Extract quoted identifiers and code-fenced terms from the rule
2. Search the codebase for their existence using grep or Grep tool
3. Flag rules that reference patterns no longer present in matching files

Step 4: Convention Drift Detection

For rules describing code conventions or patterns:

1. Identify the convention described (e.g., "all services use a configure() method")
2. Sample files matching the rule's scope
3. Check if the described pattern appears in a majority of matching files
4. Flag if <50% of files follow the described convention

Step 5: Structural Verification (nested CLAUDE.md/AGENTS.md)

For nested CLAUDE.md and AGENTS.md files, verify:

• The directory structure they describe still exists
• Commands they reference (build, test, lint) still work
• Technology/framework references match actual dependencies

Step 6: Freshness Scoring

Assign each file a score:

Score	Criteria
fresh	All globs match files, referenced files exist, described patterns verified in code
needs-review	File not modified in 60+ days, or described patterns appear in <50% of matching files, or minor drift detected
stale	Dead globs, references to deleted files, instructions contradicted by current code

Step 7: Report Generation

Produce a structured report with:

• Summary table of all files with their freshness score
• Specific findings per file (what's broken, what drifted)
• Actionable recommendations (update glob, remove reference, rewrite section)
• Priority ranking (stale items first)

Reference Navigation

Topic	Reference File	Key Contents
What makes effective rules and CLAUDE.md/AGENTS.md	references/quality-patterns.md	Root CLAUDE.md/AGENTS.md guidelines, scoped rules best practices, progressive disclosure tiers, emphasis patterns
Common mistakes to avoid	references/anti-patterns.md	Kitchen sink files, volatile imports, negative-only constraints, linter duplication, redundancy
Detecting drift and staleness	references/staleness-detection.md	Dead globs, referenced file drift, API pattern drift, version pinning, convention drift, scoring
CI integration with GitHub Actions	references/github-workflow-guide.md	Workflow architecture, setup instructions, cost optimization, claude-code-action configuration

CI Integration

For automated freshness checks on every PR, see references/github-workflow-guide.md. The workflow uses claude-code-action to review affected rules when code changes and posts findings as PR comments.

To install the CI workflow automatically, use the /install-rules-audit command.