Audit CLAUDE.md Files

Analyze CLAUDE.md files against Anthropic's official best practices with level-specific requirements.

Background

For Anthropic's official guidelines and best practices, see: @../templates/best-practices.md

Instructions

1. Determine Level

Parse arguments or auto-detect:

Location	Level	Detection
~/.claude/CLAUDE.md	user	Home directory
./CLAUDE.md (repo root)	project	Has .git sibling
src/*/CLAUDE.md	module	Inside src/lib/packages dir

2. Apply Level-Specific Requirements

For detailed quality checks and requirements by level, see: @../templates/quality-checks.md

For formatting best practices, see: @../templates/formatting-guide.md

3. Quick Reference Summary

Token Budgets:

• User: 50-100 lines (max 150)
• Project: 100-200 lines (max 300)
• Module: 30-50 lines (max 100)

Key Requirements:

• User: Personal prefs, global tools, @imports to context files
• Project: Directory structure (required!), commands, coding standards
• Module: One-line purpose, key files, module-specific conventions

Common Anti-Patterns:

• Verbose paragraphs (>3 sentences) → Convert to bullets
• Vague instructions → Be specific with examples
• Critical rules without emphasis → Add NEVER, YOU MUST
• Sections >50 lines inline → Extract to @import
• Duplicate info across levels → Keep in one place

---

4. Generate Report

## CLAUDE.md Audit Report

**Level:** [user | project | module]
**File:** [path]
**Lines:** X (Budget: Y-Z, Max: W)

### Level-Specific Compliance

#### Required Content
| Requirement | Status | Notes |
|-------------|--------|-------|
| [requirement 1] | ✅/❌ | [details] |
| [requirement 2] | ✅/❌ | [details] |

#### Content That Should Move
| Content | Current Location | Should Be In |
|---------|------------------|--------------|
| [item] | [this file] | [correct level] |

### Token Efficiency Score

**Overall: X/10**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Structure | X/10 | Headings, bullets, tables |
| Conciseness | X/10 | No verbose explanations |
| Imports | X/10 | Modular, on-demand loading |
| Emphasis | X/10 | Critical rules marked |
| Specificity | X/10 | Actionable directives |
| Level-appropriate | X/10 | Right content for this level |

### Issues Found

#### 🔴 High Priority
- **[Issue]**: [problem]
  - Line(s): X-Y
  - Fix: [action]
  - Before: `[current]`
  - After: `[improved]`

#### 🟡 Medium Priority
...

#### 🟢 Suggestions
...

### What's Working Well
- [strength]
- [strength]

---

Level-Specific Report Additions

For PROJECT Level — File Tree Check

### Directory Structure Audit

**Status:** ✅ Present and annotated | 🟡 Present but no annotations | 🔴 Missing

Current:
[paste current tree or note if missing]

Suggestions:
- [specific improvements]

For USER Level — Cross-File Check

### Duplication Check

| Content | Also In | Action |
|---------|---------|--------|
| [item] | [project file] | Remove from [location] |

For MODULE Level — Scope Check

### Scope Audit

**Focused:** ✅ Yes | ❌ No (contains project-wide content)

Content that belongs in parent:
- [item that should be in root CLAUDE.md]

---

Output Guidelines

1. Identify level first — User, project, or module determines requirements
2. Check level-specific requirements — Each level has must-have content
3. Flag misplaced content — Personal prefs in project file, etc.
4. Be specific — Line numbers, exact text, before/after examples
5. Prioritize by impact — Missing file tree (project) is high priority
6. Calculate savings — "Moving X to user-level saves ~Y lines per project"

Example Issues by Level

For detailed examples of common issues and fixes, see: @../templates/quality-checks.md

Now audit the CLAUDE.md file: $ARGUMENTS