claude-md-audit

Audit and optimize an existing CLAUDE.md — cut the noise, keep the signal.

Works on both global (~/.claude/CLAUDE.md) and project (./CLAUDE.md) files. Auto-detects which type based on content and location.

2. Read project context for comparison For project CLAUDE.md, also read:

   • package.json or pyproject.toml — dependencies, scripts
   • README.md — project description
   • tsconfig.json or equivalent — language config
   • .eslintrc / biome.json / ruff.toml — linting rules
   • .claude/settings.json — hooks configuration
   • Top-level directory structure

3. Evaluate every line against 5 criteria For each line in the file, classify it:

   REMOVE — line adds no value:

   • Discoverable from code, config files, or directory structure
   • Generic best practice any senior engineer knows
   • Duplicates information from README or other docs
   • Narrative or description rather than actionable instruction
   • Already enforced by a linter, type system, or hook

   KEEP — line earns its place:

   • Agent would make the wrong choice without it
   • Not inferable from any file in the repo
   • Specific enough to change agent behavior

   REWRITE — good intent, bad execution:

   • Too verbose (can be said in fewer words)
   • Missing the "why" (especially for "Do NOT" rules)
   • Could be merged with another line

   ADD — missing high-value context:

   • Philosophy section missing or too generic
   • Architecture decisions the agent would get wrong
   • Guardrails with no explanation of why
   • Domain context not captured anywhere

4. Generate the audit report

   Present findings in this format:

   ## Audit: [filename]
   Current: [N] lines | Target: [30 or 40] lines
   
   ### Lines to REMOVE
   | Line | Content | Reason |
   |------|---------|--------|
   | 12   | "Use 2-space indentation" | Enforced by .prettierrc |
   | 15   | "React 18 with TypeScript" | Discoverable from package.json |
   
   ### Lines to REWRITE
   | Line | Current | Suggested | Why |
   |------|---------|-----------|-----|
   | 8    | "Do not create barrel files" | "Do not create barrel files — causes circular deps" | Missing reason |
   
   ### Lines to ADD
   | Section | Suggestion | Why |
   |---------|------------|-----|
   | Philosophy | Add 3-5 engineering values | Shapes how agent thinks |
   
   ### Lines to KEEP
   [List lines that are good — earned praise only]
   

5. Propose the optimized version Write the complete rewritten file with all changes applied.

6. Show the delta

   Before: [N] lines | After: [M] lines | Removed: [X] | Added: [Y]
   Estimated token savings: ~[Z] tokens per conversation
   

7. Ask before writing Present the report and proposed version. Only write the file if the user approves. If the project would benefit from .claude/rules/ splitting, suggest it.

## Audit: ./CLAUDE.md
Current: 67 lines | Target: ~40 lines

### Lines to REMOVE (23 lines)
| Line | Content | Reason |
|------|---------|--------|
| 3    | "Built with React and TypeScript" | In package.json |
| 5-14 | Directory tree listing | Agent runs ls |
| 18   | "npm install" | Standard command |
| 19   | "npm run dev" | Standard script |
| 25   | "Use meaningful variable names" | Generic best practice |
| 26   | "Write unit tests for new features" | Generic best practice |
| 30   | "Use 2-space indentation" | In .prettierrc |

### Lines to REWRITE (3 lines)
| Line | Current | Suggested | Why |
|------|---------|-----------|-----|
| 42   | "Do not use any" | "Strict TypeScript: prefer unknown over any" | More specific |
| 45   | "Do not modify the database schema without asking" | "Do not modify /lib/db/schema.ts — migration required" | Name the file |

### Lines to ADD
| Section | Suggestion | Why |
|---------|------------|-----|
| Philosophy | "Schema-first: Zod defines contracts" | Architecture principle missing |
| Do NOT | Add reason to each guardrail | Agent needs "why" to generalize |

Before: 67 lines | After: 38 lines | Removed: 23 | Added: 2 | Rewritten: 3
Estimated token savings: ~400 tokens per conversation