claude-md-auditor

# CLAUDE.md Auditor

Validates and scores CLAUDE.md files against three authoritative sources with actionable remediation guidance.

## When to Use

- **Audit before committing** CLAUDE.md changes
- **Onboard new projects** and validate memory configuration
- **Troubleshoot** why Claude isn't following standards
- **CI/CD integration** for automated validation gates

## Validation Sources

### 1. Official Anthropic Guidance
- Memory hierarchy (Enterprise > Project > User)
- "Keep them lean" requirement
- Import syntax and limitations (max 5 hops)
- What NOT to include (secrets, generic content)
- **Authority**: Highest (requirements from Anthropic)

### 2. Community Best Practices
- 100-300 line target range
- 80/20 rule (essential vs. supporting content)
- Organizational patterns and maintenance cadence
- **Authority**: Medium (recommended, not mandatory)

### 3. Research-Based Optimization
- "Lost in the middle" positioning (Liu et al., 2023)
- Token budget optimization
- Attention pattern considerations
- **Authority**: Medium (evidence-based)

## Output Modes

### Mode 1: Audit Report (Default)

Generate comprehensive markdown report:

```
Audit my CLAUDE.md file using the claude-md-auditor skill.
```

**Output includes**:
- Overall health score (0-100)
- Category scores (security, compliance, best practices)
- Findings grouped by severity (CRITICAL → LOW)
- Specific remediation steps with line numbers

### Mode 2: JSON Report

Machine-readable format for CI/CD:

```
Generate JSON audit report for CI pipeline integration.
```

**Use for**: Automated quality gates, metrics tracking

### Mode 3: Refactored File

Generate production-ready CLAUDE.md:

```
Audit my CLAUDE.md and generate a refactored version following best practices.
```

**Output**: CLAUDE_refactored.md with optimal structure and research-based positioning

## Quick Examples

### Security-Focused Audit
```
Run a security-focused audit on my CLAUDE.md to check for secrets.
```

Checks for: API keys,