Validates code against currently loaded rules and reports compliance violations. Supports auto-fixing violations with confirmation, dry-run mode, and automatic backups. Use after implementing features, during code review, or to ensure coding standards are followed. Provides actionable feedback with line-by-line issues and suggested fixes.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Validates code against currently loaded rules and reports compliance violations. Supports auto-fixing violations with confirmation, dry-run mode, and automatic backups. Use after implementing features, during code review, or to ensure coding standards are followed. Provides actionable feedback with line-by-line issues and suggested fixes.
["Run audits early in development cycle","Focus on high-severity violations first","Provide specific, actionable fixes","Group violations by rule category","Include code examples in suggestions","Use --fix-dry-run to preview changes before applying","Review backup files (.bak) after auto-fixing"]
error_handling
graceful
streaming
supported
output_formats
["markdown","json","inline_comments"]
Executable Script
The rule-auditor skill now includes an executable script for CLI usage and programmatic validation.
Installation
No installation required - the script uses Node.js built-in modules only.
CLI Usage
# Audit a directory
node .claude/skills/rule-auditor/scripts/audit.mjs src/components/
# Audit specific file with JSON output
node .claude/skills/rule-auditor/scripts/audit.mjs src/App.tsx --format json
# Preview fixes (dry run)
node .claude/skills/rule-auditor/scripts/audit.mjs src/ --fix-dry-run
# Apply fixes (creates .bak backups)
node .claude/skills/rule-auditor/scripts/audit.mjs src/ --fix
# Audit with specific rules only
node .claude/skills/rule-auditor/scripts/audit.mjs src/ --rules nextjs,typescript
# Strict mode (fail on any violation)
node .claude/skills/rule-auditor/scripts/audit.mjs src/ --strict
Output Schema
All output conforms to .claude/schemas/skill-rule-auditor-output.schema.json and includes:
skill_name: Always "rule-auditor"
files_audited: Array of audited files with line counts
rules_applied: Rules used during audit with violation counts
compliance_score: 0-100 score based on violations
violations_found: Detailed violations with locations
fixes_applied: Applied fixes (when using --fix or --fix-dry-run)
rule_index_consulted: Boolean confirming rule index was loaded
technologies_detected: Technologies detected in codebase
Rule Auditor - Automatically validates code against your project's coding standards and rules.
- After implementing a new feature or component
- During code review to check standards compliance
- Before committing to ensure quality gates pass
- When onboarding to understand project conventions
- To generate compliance reports for teams
**Pre-Commit Hook**: Run rule audit on modified files before commit
**CI/CD Integration**: Generate JSON reports for automated quality gates
**Markdown Report Format**:
Step 1: Load Rule Index
Load the rule index to discover all available rules dynamically:
@.claude/context/rule-index.json
The index contains metadata for all 1,081+ rules in .claude/rules-master/ and .claude/rules-library/ (formerly archive).
Step 2: Filter Relevant Rules
Query the index's technology_map based on target files:
# For a specific file
audit: src/components/UserAuth.tsx
# For a directory
audit: src/components/
# For recent changes
git diff --name-only HEAD~1
Step 4: Extract Validation Patterns from Rules
Parse rule files to extract formalized validation patterns:
Look for <validation> block in rule file (deterministic approach):
<validation>
forbidden_patterns:
- pattern: "useEffect\\(.*fetch"
message: "Do not use useEffect for data fetching; use Server Components."
severity: "error"
- pattern: "console\\.log"
message: "Remove console.log statements before commit."
severity: "warning"
</validation>
OR look for validation section in rule frontmatter (legacy support):
validation:forbidden_patterns:-pattern:"useEffect\\(.*fetch"message:'Do not use useEffect for data fetching; use Server Components.'severity:'error'
Extract forbidden_patterns:
First priority: Load from <validation> block (deterministic, preferred)
Second priority: Load from validation.forbidden_patterns in frontmatter
Each pattern includes:
pattern: Regex pattern to match
message: Human-readable violation message
severity: "error" or "warning"
Fallback to pattern extraction (if no validation block/section):
Parse rule text for common patterns
Convert natural language rules to regex where possible
Use grep/pattern matching for structure checks
Note: This is slower and less consistent than using <validation> blocks
Pattern Categories to Check:
Category
Example Rule
Check Method
Naming
"Use camelCase for functions"
Regex scan
Structure
"Place components in components/ dir"
Path check
Imports
"Use ES modules, not CommonJS"
Pattern match
Types
"Avoid any, prefer unknown"
AST-level grep
Performance
"Use Server Components by default"
Directive scan
Security
"Never hardcode secrets"
Pattern detection
Formalized
validation.forbidden_patterns
Regex/grep (preferred)
Fix Field in Validation Patterns:
Each pattern can optionally include a fix field for auto-fixing:
-pattern:"console\\.log\\((.*)\\)"message:'Remove console.log statements'severity:'warning'fix:''# Empty string = delete the entire match-pattern:"const (\\w+): any"message:"Avoid using 'any' type"severity:'error'fix:'const $1: unknown'# $1 references first capture group-pattern:"var (\\w+) ="message:"Use 'const' or 'let' instead of 'var'"severity:'warning'fix:'const $1 ='# Replace var with const
Fix Replacement Syntax:
"" (empty string): Delete the entire matched pattern
"// Removed: $0": Replace with comment (where $0 is the full match)
"const $1": Use capture groups ($1, $2, etc.) from the pattern
Fixed string: Replace match with literal text
Step 5: Run Validation Checks
For each forbidden pattern:
Run grep/regex search on target files:
Use pattern from validation.forbidden_patterns
Search across all target files
Report matches with line numbers
Report matches:
Include line number and file path
Include message from pattern definition
Include severity (error/warning)
Show code snippet with match highlighted
Aggregate results by severity:
Group errors separately from warnings
Count violations per pattern
Sort by severity and frequency
Step 6: Generate Compliance Report
Output a structured report with violations, warnings, and passed rules.
Step 7: Quick-Fix Mode (Optional)
When --fix, --fix-auto, or --fix-dry-run flags are provided, automatically apply fixes for violations that have a fix field defined.
Fix Mode Behavior:
--fix-dry-run (Safe Preview):
Scan for violations with fix definitions
Show diff preview of changes without modifying files
Display before/after for each fix
No file modifications occur
Useful for reviewing impact before applying
--fix (Interactive Mode):
Create .bak backup file before any modification
Show diff preview for each fixable violation
Prompt user for confirmation: "Apply this fix? (y/n/all/skip)"
y: Apply this fix and continue
n: Skip this fix and continue
all: Apply all remaining fixes without prompting
skip: Skip all remaining fixes
Apply confirmed fixes using Edit tool
Report summary of applied vs skipped fixes
--fix-auto (Batch Mode):
Create .bak backup file before any modification
Apply all fixable violations automatically
No user prompts (fully automated)
Generate detailed log of all changes
Useful for CI/CD pipelines or bulk cleanup
Backup Behavior:
Backup file: <original-file>.bak
Created before first modification to each file
Contains original file contents
Allows manual rollback if needed
Example: src/App.tsx → src/App.tsx.bak
Diff Preview Format:
File: src/components/UserAuth.tsx
Line 23:
- console.log('User authenticated:', user);+ // Removed: console.log('User authenticated:', user);
Line 45:
- const user: any = await getUser();+ const user: unknown = await getUser();
Fix Application Process:
Read target file
Create backup if not in dry-run mode
Apply regex replacement using fix pattern
Handle capture group substitutions ($1, $2, etc.)
Write modified content back to file
Log change to fix report
Limitations:
Only fixes violations with fix field defined in rule
Complex refactorings require manual intervention
Multiline fixes may need manual review
Some patterns may require AST-level transformation
</execution_process>
<audit_patterns>
Next.js / React Audit:
CHECK: 'use client' directive present when using useState, useEffect, useContext
CHECK: Server Components for data fetching (no useEffect for fetch)
CHECK: Image optimization using next/image
TypeScript Audit:
CHECK: Type safety - No any types, interfaces for object shapes
CHECK: Naming conventions - PascalCase for Components, camelCase for functions
Python/FastAPI Audit:
CHECK: Async patterns - async def for I/O operations
CHECK: Type hints - All function parameters typed
</audit_patterns>
<best_practices>
Run Early: Audit during development, not just before commit
Fix as You Go: Address violations immediately while context is fresh
Customize Rules: Adjust rule severity in manifest.yaml for your team
Track Trends: Monitor violation counts over time to measure improvement
Educate Team: Use audit reports in code reviews to teach standards
Preview First: Always run --fix-dry-run before --fix-auto to review changes
Test After Fixing: Run tests after auto-fixing to ensure no functionality broke
Keep Backups: Don't delete .bak files until changes are verified
Review Diffs: Use git diff to review all changes before committing
Start Small: Test auto-fix on single files before running on entire codebase
</best_practices>
Quick-Fix Mode
The rule-auditor now supports automatic fixing of violations through three modes: preview, interactive, and batch.
Fix Modes
Mode
Flag
Behavior
Use Case
Preview
--fix-dry-run
Show changes without modifying files
Review impact before applying
Interactive
--fix
Prompt for confirmation on each fix
Careful, selective fixing
Batch
--fix-auto
Apply all fixes automatically
Bulk cleanup, CI/CD
Adding Fix Definitions to Rules
To make violations auto-fixable, add a fix field to validation patterns in your rule files:
In <validation> block:
<validation>
forbidden_patterns:
- pattern: "console\\.log\\((.*)\\)"
message: "Remove console.log statements before commit"
severity: "warning"
fix: "" # Empty = delete entire match
- pattern: "const (\\w+): any"
message: "Avoid using 'any' type"
severity: "error"
fix: "const $1: unknown" # Replace with unknown
- pattern: "var (\\w+) ="
message: "Use 'const' or 'let' instead of 'var'"
severity: "warning"
fix: "const $1 =" # Replace var with const
</validation>
Comment Out: Replace with comment preserving original code
pattern:'debugger;'fix:'// debugger;'
Safety Features
Automatic Backups: Creates .bak file before any modification
Diff Preview: Shows before/after for all fixes
Dry-Run Mode: Test fixes without modifying files
Interactive Confirmation: Review each fix before applying
Rollback Support: Restore from .bak files if needed
Example Workflow
# 1. Preview what would be fixed
/audit src/ --fix-dry-run
# 2. Apply fixes with confirmation
/audit src/components/UserAuth.tsx --fix
# 3. Review changes
git diff
# 4. Run tests
npm test# 5. If issues occur, rollbackmv src/components/UserAuth.tsx.bak src/components/UserAuth.tsx
# 6. If all good, commit
git add src/
git commit -m "fix: auto-fix rule violations"# 7. Clean up backupsrm **/*.bak
Creating Effective Fix Patterns
Good Fix Patterns (Safe, Deterministic):
Simple find-replace operations
Type annotations (any → unknown)
Variable declarations (var → const)
Import statement updates
Comment/uncomment code
Formatting fixes
Poor Fix Patterns (Manual Review Required):
Complex refactorings
Logic changes
Multiline transformations
Context-dependent fixes
AST-level transformations
Best Practices for Fix Definitions:
Keep fixes simple and deterministic
Test fix patterns on sample code before deploying
Use capture groups to preserve variable names
Prefer commenting over deletion for debugging code
Document why a fix is safe in the rule message
Consider edge cases where fix might break code
Limitations
Only fixes violations with fix field defined
Regex-based replacements only (no AST manipulation)
Complex refactorings require manual intervention
Multiline patterns may need special handling
Some fixes may require post-fix manual adjustments
For complex transformations beyond regex replacement, consider using the refactoring-specialist agent.
## Rule Audit Report**Target**: src/components/UserAuth.tsx
**Rules Applied**: nextjs.mdc, typescript.mdc, react.mdc
**Scan Date**: {{timestamp}}
### Summary-**Pass**: 12 rules
-**Warn**: 3 rules
-**Fail**: 2 rules
### Violations#### FAIL: Use Server Components by default-**File**: src/components/UserAuth.tsx:1
-**Issue**: Missing 'use client' directive but uses useState
-**Rule**: nextjs.mdc > Components
-**Fix**: Add 'use client' at file top, or refactor to Server Component
#### FAIL: Avoid using `any`-**File**: src/components/UserAuth.tsx:45
-**Issue**: `const user: any = await getUser()`-**Rule**: typescript.mdc > Type System
-**Fix**: Define proper User interface
#### WARN: Minimize use of 'useEffect'-**File**: src/components/UserAuth.tsx:23
-**Issue**: useEffect for data fetching
-**Rule**: nextjs.mdc > Performance
-**Suggestion**: Consider Server Component with async/await
### Passed Rules- ✅ Use TypeScript strict mode
- ✅ Use lowercase with dashes for directories
- ✅ Implement proper error boundaries
... (12 more)
</formatting_example>
<code_example>
JSON Output Format (for CI/CD):
{"target":"src/components/","timestamp":"2025-11-29T10:00:00Z","rules_applied":["nextjs.mdc","typescript.mdc"],"summary":{"pass":12,"warn":3,"fail":2},"violations":[{"severity":"fail","rule":"typescript.mdc","pattern":"Avoid using any","file":"src/components/UserAuth.tsx","line":45,"code":"const user: any = await getUser()","fix":"Define User interface"}]}
</code_example>
<code_example>
Inline Comments Format:
// RULE_VIOLATION: typescript.mdc > Avoid using `any`// FIX: Define User interface with proper typesconstuser: any = awaitgetUser(); // ❌ FAIL
</code_example>
<code_example>
Pre-Commit Hook:
#!/bin/bash# .claude/hooks/pre-commit-audit.sh# Hook: PreToolUse (for Edit, Write tools)# Run rule audit on modified files
modified=$(git diff --cached --name-only)
for file in$modified; do
audit_result=$(claude skill rule-auditor --target "$file" --format json)
ifecho"$audit_result" | jq -e '.summary.fail > 0' > /dev/null; thenecho"Rule violations found in $file"exit 1
fidone
# GitHub Actions example-name:RuleAuditrun:|
claude skill rule-auditor --target src/ --format json > audit-report.json
if [ $(jq '.summary.fail' audit-report.json) -gt 0 ]; then
echo "::error::Rule violations detected"
exit 1
fi
</code_example>
<usage_example>
Quick Commands:
# Audit current file
/audit this file
# Audit a specific directory
/audit src/components/
# Audit with specific rules only
/audit src/ --rules nextjs,typescript
# Generate CI-friendly output
/audit src/ --format json --strict
# Show only failures
/audit src/ --severity fail
# Preview fixes without applying (dry-run)
/audit src/components/ --fix-dry-run
# Apply fixes with confirmation
/audit src/components/UserAuth.tsx --fix
# Apply all fixes automatically (batch mode)
/audit src/ --fix-auto
# Dry-run with JSON output for CI/CD
/audit src/ --fix-dry-run --format json
</usage_example>
<usage_example>
Quick-Fix Mode Examples:
Example 1: Dry-Run Preview
Command:
/audit src/components/UserAuth.tsx --fix-dry-run
Output:
## Fix Preview (Dry-Run Mode)
### Fixable Violations: 3
#### Fix 1/3
File: src/components/UserAuth.tsx:23
Rule: Remove console.log statements
Severity: warning
- console.log('User authenticated:', user);+ // Removed: console.log('User authenticated:', user);
#### Fix 2/3
File: src/components/UserAuth.tsx:45
Rule: Avoid using 'any' type
Severity: error
- const user: any = await getUser();+ const user: unknown = await getUser();
#### Fix 3/3
File: src/components/UserAuth.tsx:67
Rule: Use 'const' or 'let' instead of 'var'
Severity: warning
- var isAuthenticated = true;+ const isAuthenticated = true;---
Summary: 3 fixable violations found
No files modified (dry-run mode)
Example 2: Interactive Fix Mode
Command:
/audit src/components/UserAuth.tsx --fix
Interactive Session:
Creating backup: src/components/UserAuth.tsx.bak
Fix 1/3:
File: src/components/UserAuth.tsx:23
Rule: Remove console.log statements
- console.log('User authenticated:', user);
+ // Removed: console.log('User authenticated:', user);
Apply this fix? (y/n/all/skip): y
✓ Applied fix 1/3
Fix 2/3:
File: src/components/UserAuth.tsx:45
Rule: Avoid using 'any' type
- const user: any = await getUser();
+ const user: unknown = await getUser();
Apply this fix? (y/n/all/skip): all
✓ Applied fix 2/3
✓ Applied fix 3/3
---
Fix Summary:
- Total violations: 3
- Fixes applied: 3
- Fixes skipped: 0
- Backup created: src/components/UserAuth.tsx.bak
Run git diff to review changes.
Example 3: Batch Auto-Fix
Command:
/audit src/ --fix-auto
Output:
## Auto-Fix Report
Creating backups for modified files...
✓ src/components/UserAuth.tsx.bak
✓ src/components/Profile.tsx.bak
✓ src/utils/helpers.ts.bak
Applying fixes...
src/components/UserAuth.tsx:
✓ Line 23: Removed console.log statement
✓ Line 45: Changed 'any' to 'unknown'
✓ Line 67: Changed 'var' to 'const'
src/components/Profile.tsx:
✓ Line 12: Removed console.log statement
✓ Line 89: Changed 'var' to 'const'
src/utils/helpers.ts:
✓ Line 34: Changed 'any' to 'unknown'
✓ Line 78: Changed 'any' to 'unknown'
---
Fix Summary:
- Files modified: 3
- Total fixes applied: 7
- Backups created: 3
Next steps:
1. Run 'git diff' to review all changes
2. Run tests to ensure fixes didn't break functionality
3. If issues occur, restore from .bak files
