claude-md-auditor

CLAUDE.md Auditor

Audit and improve CLAUDE.md files based on Claude Code Best Practices.

Audit Process

Step 1: Read the Target CLAUDE.md

Read the CLAUDE.md file specified by $ARGUMENTS. If no path is provided, look for CLAUDE.md in the current working directory.

Step 2: Load Best Practices Reference

Read references/best-practices.md to understand the evaluation criteria.

Step 3: Analyze Each Section

For each section in CLAUDE.md, evaluate:

1. Necessity: Would removing this cause Claude to make mistakes?
2. Redundancy: Can Claude infer this from the codebase?
3. Accuracy: Is this still accurate and relevant?
4. Specificity: Is this actionable or too vague?
5. Length: Is this concise or overly verbose?

Step 4: Generate Audit Report

Output a structured report in this format:

# CLAUDE.md Audit Report

## Summary
- Total lines: X
- Lines to remove: Y
- Lines to improve: Z
- Health score: X/10

## Issues Found

### Redundant Content
[List items that Claude can infer from code]

### Overly Verbose
[List sections that should be condensed]

### Stale/Outdated
[List references to old patterns or removed features]

### Vague Instructions
[List non-actionable guidance]

### Missing Information
[List recommended additions based on codebase analysis]

## Recommended Changes

### Remove
[Specific lines/sections to delete]

### Condense
[Suggestions for making sections more concise]

### Add
[Recommended additions with rationale]

Step 5: Offer to Apply Changes

After presenting the report, ask the user if they want to apply the recommended changes automatically.

Quality Targets

• Ideal length: 50-200 lines
• Maximum length: 500 lines (beyond this, Claude may ignore instructions)
• Focus: Actionable, specific, non-obvious information only