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

claude-md-audit

claude-md-audit

More from reizam/claude-md-templates

claude-md-global

claude-md-project