---
name: claude-md-audit
description: Walk through a CLAUDE.md file line by line and flag lines for deletion, movement, or tightening. Checks against the "does this apply to every project?" and "would removing this cause mistakes?" tests. Use monthly.
---

# CLAUDE.md Audit

When invoked, read the specified CLAUDE.md file (global, workspace, or project) and audit it against size + relevance rules.

## Approach

1. **Read the file.** Count total lines. Flag immediately if:
   - Global CLAUDE.md over 50 lines (target under 25)
   - Project CLAUDE.md over 80 lines (target 30-60)
   - Workspace CLAUDE.md over 20 lines
2. **Walk through line by line.** For each line / rule, decide:
   - **KEEP** - applies to every session for this scope, removing it would cause mistakes
   - **MOVE** - project-specific rule in a global file, or global rule in a project file
   - **DELETE** - redundant, already default behaviour, "write clean code" style noise, or vague
   - **TIGHTEN** - the rule exists but is wordy or vague; propose a shorter version
3. **Check for specific patterns:**
   - Code formatting rules (usually DELETE - Claude formats well by default)
   - "Be helpful" / "explain your reasoning" (DELETE - baseline behaviour)
   - Stock phrases like "use best practices" (DELETE)
   - Project-specific rules in global files (MOVE)
   - Rules that contradict other rules (flag + ask user to resolve)
   - Client names or API keys (DELETE immediately - never in CLAUDE.md)

## Output format

```
Auditing: ~/.claude/CLAUDE.md (42 lines, target under 25)

Line 1-5 [Who I am]: KEEP - applies every session
Line 7-12 [How I work]: KEEP - every session
Line 14 [Use 2-space indentation]: DELETE - Claude formats code well by default
Line 18 [Shopify-specific API notes]: MOVE - project-specific, belongs in that project's CLAUDE.md
Line 22 [Write clean code]: DELETE - baseline behaviour
Line 28-34 [Safety rails]: KEEP - non-negotiables

Summary:
- 3 lines to delete
- 1 line to move
- 38 lines to keep
- After cuts: 21 lines (on target)

Want me to apply these changes?
```

## Rules

- Never silently edit the CLAUDE.md. Present the audit, wait for user approval, then apply.
- CAPS are allowed for critical safety rules. Don't flag them as noise.
- `<!-- comments -->` are free (stripped before sending to Claude). Don't flag them as bloat.
- `@file` imports are fine even if they look unusual - they're a valid way to stay under the line limit while including more context.
- If the file is already lean, say so explicitly ("under 25 lines, well-structured - no changes needed").
- For project CLAUDE.md audits, check for stale info: completed pending items still listed, outdated account IDs, old status.
- Never move credentials, API keys, or secrets. If found, flag as DELETE immediately - they should never be in a CLAUDE.md file at all.