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.
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
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
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]
Propose the optimized version Write the complete rewritten file with all changes applied.
Show the delta
Before: [N] lines | After: [M] lines | Removed: [X] | Added: [Y] Estimated token savings: ~[Z] tokens per conversation
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