← Toolkit
Plugin

CLAUDE.md Audit

A Claude Code plugin that scores your CLAUDE.md and .claude/rules/ files against proven best practices, then hands you a scorecard with line-referenced, actionable fixes. Includes the /claude-brain:audit skill, the one I built after auditing 30+ repos.

Get notified when new tools drop, plus walkthroughs and Claude Code tips.

Get the plugin

The install commands for claude-brain ship in the Substack welcome email, along with every other skill in the toolkit. Subscribe above and they land in your inbox.

How It Works

Run /claude-brain:audit in any repo, or just ask “is my CLAUDE.md good?” and the skill auto-triggers. It reads only; it never edits your files.

  1. 1Discovers every CLAUDE.md and .claude/rules/*.md file in the repo
  2. 2Reads each scored file in full, plus global and parent files for context
  3. 3Skims package.json, go.mod, Makefile, and friends to catch stale or derivable lines
  4. 4Scores each file against the Signal / Noise / Structure rubric
  5. 5Hands back a score out of 11 and your top 3 fixes, every finding line-referenced

What It Scores

Every file earns a score from -9 to 11: Signal plus Structure, minus Noise. The three checklists:

Signal

what should be there max +8
S1

System names

Internal codenames mapped to plain descriptions: “Atlas = internal search engine.”

S2

Non-obvious defaults

Branch names, package managers, ports, env quirks Claude would otherwise guess wrong.

S3

Gotchas

Hard-won failure modes that name a specific mechanism and a concrete consequence.

S4

Behavioral guardrails

Attempt limits, confirmation requirements, forbidden actions.

S5

Decision framework

Priority ordering for when several approaches are all valid.

Noise

what shouldn't penalties
N1

The Novel

Over 300 lines: every extra line dilutes the ones that matter.

N2

The Duplicate

3+ lines Claude can derive from a glob, a signature, or git.

N3

The Wishlist

“Write clean code” and other instructions too vague to change behavior.

N4

The Stale Doc

References to files, packages, or branches that no longer match the repo.

N5

The Settings Leak

settings.json content that belongs in config, not prose.

N6

The Railroader

Rigid step-by-step scripts that strip Claude of judgment.

N7

The Template Dump

Unedited /init boilerplate that adds no repo-specific value.

Structure

how it's organized max +3
T1

Includes the “why”

Rules carry their reasoning, so Claude generalizes to cases the rule didn't list.

T2

No hierarchy duplication

Doesn't repeat what a global or workspace file already covers.

T3

Right-sized

30–150 lines for a CLAUDE.md; 5–80 for a modular rules file.

The Scorecard

You get one of these per file: a score, a checked-off rubric, the noise it found, and the three highest-value fixes, each with a line reference:

### CLAUDE.md

Score: 6 / 11   (Signal +5/8 · Noise -2 · Structure +3/3)

Signal
[x] S1 System names: "Atlas = internal search" (line 12)
[ ] S2 Non-obvious defaults: MISSING
[x] S3 Gotchas (+2): cache key breaks on extra query params (line 34)

Noise
N2 The Duplicate: 18-line directory tree (lines 40-58); a Glob derives it.

Top 3
1. Add: a non-obvious default (the main branch is `develop`, not `main`).
2. Remove: the directory tree (lines 40-58).
3. Improve: turn "write clean code" into a named convention.

Two Modes

/claude-brain:audit

Per-file scorecards. Pass a path to audit one file, or run it bare to discover and score every in-scope file in the repo.

/audit hierarchy

Looks at the whole stack at once (global, workspace, repo, and rules files) for duplication, conflicts, and coverage gaps between files.

View source on GitHub →