140 lines
4.0 KiB
Markdown
140 lines
4.0 KiB
Markdown
---
|
|
name: claude-md-auditor
|
|
description: Use PROACTIVELY when reviewing CLAUDE.md configurations, onboarding new projects, or before committing memory file changes. Validates against official Anthropic documentation, community best practices, and LLM context optimization research. Detects security violations, anti-patterns, and compliance issues. Not for runtime behavior testing or imported file validation.
|
|
---
|
|
|
|
# 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
|