KevinZai CLAUDE.md Auditor
Compares your CLAUDE.md instructions against the real state of the codebase and suggests concrete improvements.
What It Checks
1. Stale References
- File paths mentioned in CLAUDE.md that no longer exist
- Commands referenced that aren't in package.json scripts
- Dependencies mentioned that aren't in package.json
- Tool/framework references that don't match installed versions
2. Missing Context
- Key directories not documented (src/, lib/, tests/)
- Package.json scripts not mentioned
- Environment variables used in code but not documented
- MCP servers configured but not referenced
- Git hooks or CI workflows not mentioned
3. Cache Optimization
- Is static content first, dynamic last? (cache-friendly ordering)
- Are frequently-referenced paths at the top?
- Is the file under 500 lines? (diminishing returns above this)
- Are there duplicate instructions that waste tokens?
4. Token Efficiency
- Verbose instructions that could be condensed
- Commented-out or TODO sections wasting context
- Redundant path listings that could use glob patterns
- Long example blocks that could be shortened
Process
Step 1: Read CLAUDE.md
Read the project's CLAUDE.md file completely.
Step 2: Scan Codebase
Use Glob and Bash to check:
# Files that exist
ls -la package.json tsconfig.json .env* Dockerfile docker-compose.yml
# Package scripts
node -e "console.log(Object.keys(require('./package.json').scripts || {}).join(', '))"
# Key directories
ls -d src/ lib/ tests/ app/ pages/ components/ 2>/dev/null
# Installed deps
node -e "var p=require('./package.json'); console.log(Object.keys({...p.dependencies,...p.devDependencies}).join(', '))"
Step 3: Cross-Reference
For each instruction in CLAUDE.md:
- Does the referenced file/path exist?
- Does the referenced command work?
- Is the information current?
Step 4: Report
Present findings via AskUserQuestion:
CLAUDE.md Audit Results:
━━━━━━━━━━━━━━━━━━━━━━
File: CLAUDE.md (342 lines)
Stale References: 3
X "src/utils/auth.ts" — file doesn't exist (was it renamed?)
X "npm run deploy" — no deploy script in package.json
X "Uses Prisma" — prisma not in dependencies
Missing Context: 4
! tests/ directory not documented (14 test files)
! .github/workflows/ not mentioned (CI exists)
! Environment: NEXT_PUBLIC_API_URL used but not documented
! MCP server "context7" configured but not referenced
Cache Optimization: 2
> Move "Coding Standards" section above "API Reference" (more frequently needed)
> Remove 45 lines of commented-out old instructions
Token Savings Estimate: ~2,100 tokens/session
Apply fixes?
> Yes, fix all automatically
Show me each fix first
Export report only