best-practices-audit

Original：🇺🇸 English

Translated

Audits and auto-fixes a project's CLAUDE.md against Anthropic best practices. Activates during ship phase — checks conciseness, enforces @import structure for detailed docs, auto-excludes bloat, identifies hook candidates, and auto-fixes structural issues. Flags content questions for developer review.

1installs

Sourcebrite-nites/britenites-claude-plugins

Added on2026-03-02

NPX Install

npx skill4agent add brite-nites/britenites-claude-plugins best-practices-audit

SKILL.md Content

View Translation Comparison →

Best Practices Audit

You are auditing a project's CLAUDE.md to ensure it follows Anthropic's official best practices and stays effective as the project evolves. This runs after compound learnings are captured, to catch any drift.

When to Activate

Invoked by the
```
ship
```
command after compound-learnings
The
```
/workflows:setup-claude-md
```
command includes similar audit logic
After significant CLAUDE.md changes

Reference

Read the best-practices reference from

.claude/skills/setup-claude-md/claude-code-best-practices.md

. If the file is not accessible, use the audit checklist below as the authoritative guide.

Audit Checklist

1. Size Check

CLAUDE.md should be under ~100 lines. Performance degrades with length.

Under 80 lines: Good
80-120 lines: Acceptable, look for extraction opportunities
Over 120 lines: Must extract sections to
```
docs/
```
with
```
@import
```

2. Required Sections

Every CLAUDE.md should have (in this order):

## Build & Test Commands     — How to build, test, lint, typecheck
## Code Conventions          — Only non-obvious, project-specific ones
## Architecture Decisions    — Key patterns and data flow
## Gotchas & Workarounds     — Things that will bite you

Optional but valuable:

## Environment Setup         — env vars, secrets, dependencies
## Workflow Rules            — branch, commit, PR conventions

Flag missing required sections.

3. @import Structure

Detailed documentation should be extracted to

docs/

and referenced via

@import

:

markdown

# CLAUDE.md (short, focused)
@docs/api-conventions.md
@docs/data-model.md
@docs/deployment.md

Check for:

Sections over ~10 lines that are domain-specific → extract to
```
docs/
```
Architecture docs inline → extract to
```
docs/architecture.md
```
Convention details inline → extract to
```
docs/conventions.md
```
API documentation inline → extract or use context7 instead

4. Auto-Exclude Patterns

Flag and suggest removal of:

Pattern	Why
Standard language conventions	Claude already knows these
"Write clean code" / "Follow best practices"	Self-evident
Detailed API documentation	Link to docs or use context7
File-by-file codebase descriptions	Claude can read the code
Long explanations or tutorials	Extract to docs/
Information that changes frequently	Will go stale quickly
Generic advice not specific to this project	Adds noise without value

5. Command Accuracy

Verify all commands in CLAUDE.md actually work:

Read
```
package.json
```
scripts (or equivalent)
Cross-reference with CLAUDE.md build/test/lint commands
Flag any commands that don't match reality:
- Command listed but script doesn't exist
- Script exists but command not listed
- Command syntax is wrong

6. Hook Candidates

Identify CLAUDE.md rules that should be deterministic hooks instead:

"Always run lint before committing" → pre-commit hook
"Never use
```
any
```
type" → TypeScript strict config
"Format with Prettier" → PostToolUse format hook
"Check for secrets before pushing" → PreToolUse hook

Advisory rules that can be enforced deterministically should be hooks, not CLAUDE.md lines.

7. Staleness Check

Look for entries that reference:

Files that no longer exist
Patterns that were replaced
Dependencies that were removed
Commands that were changed
Conventions that evolved

Auto-Fix vs Flag

Auto-Fix (do silently)

Reorder sections to match the recommended order
Remove obviously self-evident entries ("write clean code")
Fix command syntax if the correct command is clear from
```
package.json
```
Extract sections over 10 lines to
```
docs/
```
with
```
@import
```
(create the file)

Flag for Developer (ask before changing)

Removing content that might be intentional
Changing conventions that affect team workflow
Adding new sections based on codebase analysis
Pruning entries you're not 100% certain are stale

Report

## CLAUDE.md Audit

**Size**: [N] lines ([status: good / needs extraction / critical])

**Auto-fixed**:
- [list of changes made automatically]

**Needs your input**:
- [list of flagged items with context]

**Recommendations**:
- [suggestions for improvement]

**Hook candidates**:
- [rules that should become hooks]

Rules

Every line in CLAUDE.md should earn its place — one precise instruction is worth ten generic ones
Auto-fix structural issues but never auto-remove content without flagging
The goal is a CLAUDE.md that makes agents maximally effective, not one that documents everything
Reference
```
_shared/validation-pattern.md
```
for self-checking
Prefer
```
@import
```
for anything that would make the core file unwieldy
Don't add sections for the sake of completeness — only add what's genuinely useful