best-practices-audit

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 /britenites: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:

# 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:

1. Read package.json scripts (or equivalent)
2. Cross-reference with CLAUDE.md build/test/lint commands
3. 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