claudemd-audit

A small Claude Code skill that classifies the rules in a CLAUDE.md by enforcement type.

The problem

Every CLAUDE.md grows. Nobody shrinks one. Lines compete for attention on every turn, and once the file is large, the rule that matters becomes a needle in your own haystack. Worse, a lot of what ends up in a CLAUDE.md can't be enforced by prose at all. "Never edit migrations" is a deterministic rule that belongs in a hook, where it actually fires, not a sentence you hope the model reads on the right turn.

claudemd-audit reads a CLAUDE.md, identifies the instruction-bearing lines, and sorts each one into a bucket:

• deterministic-eligible — could be enforced by a hook or rule instead of prose
• probabilistic-only — genuinely needs model judgment, keep it
• vague — no actionable signal, cut it
• redundant — near-duplicate of another rule

The output is a markdown or JSON report showing where your token budget is being spent and what could move out of prose and into deterministic enforcement.

Install

Drop the folder into .claude/skills/:

git clone https://github.com/blacksundev/claudemd-audit ~/.claude/skills/claudemd-audit

Or install it at the project level under .claude/skills/ inside your repo.

Usage

Ask Claude:

audit my CLAUDE.md

The skill auto-loads, runs audit.py, and reports its findings.

For a manual run:

python audit.py path/to/CLAUDE.md

JSON output:

python audit.py path/to/CLAUDE.md --json

See DEMO.md for a worked example with real input and real output.

How it works

The heuristics are intentionally simple. They catch common signal patterns:

• imperative verbs at the start of bullets
• strong rule keywords (never, always, must not)
• judgment keywords (consider, prefer, match the)
• code spans (paths, commands, exact strings)
• vague aspirational tokens
• near-duplicate lines

They will misclassify edge cases. The output is a starting point for review, not a final word — run it, then read the output line by line. The classification is a sort filter, not a verdict.

Sophistication here would add false precision. A classifier that's right 78% of the time and obviously a heuristic is more useful than one that's right 84% of the time but reads like an oracle you stop checking.

The argument behind it

The framing is laid out in the article: CLAUDE.md is a budget, not a system prompt. Treat the file as a finite budget. The audit shows you where it's being spent and what could move to hooks instead.

Contributing

Issues and PRs welcome. If you find a misclassification that matters, open an issue with the line that was misread and the bucket you'd expect. False positives on the classifier are the most useful thing to report.

License

Apache 2.0. See LICENSE.

---

Supporting this project

claudemd-audit is apache-2.0 and free. it stays free.

if you want the enforcement half — pre-built claude code hooks and tight CLAUDE.md templates i've been refining on real codebases — i sell a small pack on gumroad. five tested hooks (block-dangerous-commands, protect-paths, scan-secrets, conventional-commits, format-on-save) and three CLAUDE.md templates that push the deterministic rules into the hooks where they belong. €19, 30-day refund. buying it funds work on this repo.

free finds, paid fixes → https://blacksundev.gumroad.com/l/ylbgvm

if you just want the audit tool, you already have everything. carry on.