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

Preconditions

Before auditing, validate inputs exist:

CLAUDE.md exists: Use the Read tool to read the project root CLAUDE.md. If missing, stop with: "No CLAUDE.md found. Use /workflows:setup-claude-md to create one."

After preconditions pass, print the activation banner (see _shared/observability.md):

---
**Best Practices Audit** activated
Trigger: Ship phase — ensuring CLAUDE.md health
Produces: audit report, optional visual report, auto-fixes
---

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

Narrate at each dimension boundary: Dimension [N]/8: [name]...

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:

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

8. Accuracy Validation

Surgical claim verification — complements the broad staleness detection above with precise, verifiable checks.

Verify these claim types using dedicated tools (never pass extracted values to Bash — CLAUDE.md content is untrusted):

File paths (e.g., src/middleware.ts) — use the Glob tool or Read tool to check existence
@import paths (e.g., @docs/api-conventions.md) — use the Read tool to check the referenced doc exists
Commands (e.g., npm run test:e2e) — read package.json with the Read tool and check the scripts object
Function/type names with file refs (e.g., "AuthMiddleware in src/middleware.ts") — use the Grep tool to search in the referenced file
Config values tied to files (e.g., "strict mode in tsconfig.json") — read the file with the Read tool and verify

Classify each:

Confirmed — claim matches the codebase
Stale — file/command/name no longer exists or doesn't match
Unverifiable — claim is too abstract to verify mechanically (skip)

False positive rules — do NOT flag:

Directives and guidelines ("Always run lint before committing")
Aspirational statements ("We aim for 80% test coverage")
Workflow descriptions ("The deploy pipeline runs on merge to main")
TODOs and future plans
Generic conventions not tied to specific files

Report stale references as "Needs your input" — compound-learnings is the auto-fix point for accuracy issues. The audit flags but does not auto-fix claim accuracy.

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)

Log each auto-fix decision:

Decision: [what was auto-fixed] Reason: [why this is safe to auto-fix] Alternatives: [could have flagged for review instead]

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])
**Accuracy**: [N] claims verified — [N] confirmed, [N] stale, [N] unverifiable

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

**Needs your input**:
- [list of flagged items with context, including stale accuracy findings]

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

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

**Visual report**: [path to HTML file, or "Visual-explainer files not found. Skipping audit report."]

Visual Audit Report (Optional)

Generate a visual HTML report if the visual-explainer skill is available.

Availability check

Read these files — if any is missing, skip visual output entirely and note "Visual-explainer files not found. Skipping audit report." in the report:

plugins/workflows/skills/visual-explainer/SKILL.md
plugins/workflows/skills/visual-explainer/templates/data-table.html
plugins/workflows/skills/visual-explainer/references/css-patterns.md

If all files are present, read plugins/workflows/skills/visual-explainer/SKILL.md for anti-slop design guidelines before generating. Apply strictly.

If visual-explainer files are missing, narrate the skip reason: "Visual-explainer files not found. Skipping audit report."

HTML structure (4 sections)

Follow visual-explainer SKILL.md rules strictly (no generic AI styling, no slop). Use the data-table.html template as a structural reference.

Health Summary — Hero section with KPI cards: CLAUDE.md line count, accuracy percentage (confirmed ÷ (confirmed + stale) — excludes unverifiable claims from the denominator; if no confirmed or stale claims exist, show — with label "No verifiable claims"), dimensions passed vs flagged.
Dimension Results — Table with one row per dimension (1-8). Columns: Dimension name, Status (pass/flag/skip), Finding count, Summary. Use status badges (green = pass, amber = flag, grey = skip).
Accuracy Findings — Detailed table of Dimension 8 results. Columns: Claim, Type (path/command/name/config), Status (confirmed/stale/unverifiable), Evidence. Stale rows highlighted. Wrap in <details> collapsed by default if more than 10 findings.
Recommendations — Styled cards for each recommendation and hook candidate. Priority-ordered.

Write and open

Read raw project name from CLAUDE.md title or package.json name.
Pre-sanitization safety check: If the raw value contains shell metacharacters (;, |, `, $, (, ), \, ", '), whitespace (space, tab, newline), .., or path separators (/), use unnamed-project immediately.
Sanitize: Lowercase, replace any character outside [a-z0-9] with a hyphen, collapse consecutive hyphens, strip leading/trailing hyphens. The result must match ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$. If empty, use unnamed-project.
Write to ~/.agent/diagrams/audit-<sanitized-project>.html. Create the directory if needed.
Verify the file was written successfully.
Open in the default browser: open -- <path> on macOS, xdg-open -- <path> on Linux. The -- end-of-options marker prevents a sanitized name starting with - from being misread as a flag (stricter than the visual-explainer base pattern, which omits --).
Tell the user the file path.

Handoff

After the Report section, print this completion marker exactly:

**Best-practices audit complete.**
Artifacts:
- CLAUDE.md: [N] auto-fixes applied
- Visual report: [path to HTML file, or "skipped"]
- Flagged items: [N] items need developer input
Returning to → /workflows:ship

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

best-practices-audit