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, tokens, passwords, connection strings, private keys

Multi-Tier Audit

Audit CLAUDE.md files in my project hierarchy (Enterprise, Project, User tiers).

Checks each tier and reports conflicts between them.

Score Interpretation

Overall Health (0-100):

• 90-100: Excellent (minor optimizations only)
• 75-89: Good (some improvements recommended)
• 60-74: Fair (schedule improvements)
• 40-59: Poor (significant issues)
• 0-39: Critical (immediate action required)

Category Targets:

• Security: 100 (any issue is critical)
• Official Compliance: 80+
• Best Practices: 70+

Finding Severities

• CRITICAL: Security risk (fix immediately)
• HIGH: Compliance issue (fix this sprint)
• MEDIUM: Improvement opportunity (next quarter)
• LOW: Minor optimization (backlog)

Reference Documentation

Detailed validation criteria and integration examples:

• reference/official-guidance.md - Complete Anthropic documentation compilation
• reference/best-practices.md - Community-derived recommendations
• reference/research-insights.md - Academic research findings
• reference/anti-patterns.md - Catalog of common mistakes
• reference/ci-cd-integration.md - Pre-commit, GitHub Actions, VS Code examples

Limitations

• Cannot automatically fix security issues (requires manual remediation)
• Cannot test if Claude actually follows the standards
• Cannot validate imported files beyond path existence
• Cannot detect circular imports

Success Criteria

A well-audited CLAUDE.md achieves:

• Security Score: 100/100
• Official Compliance: 80+/100
• Overall Health: 75+/100
• Zero CRITICAL findings
• < 3 HIGH findings

---

Version: 1.0.0 | Last Updated: 2025-10-26