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?$ . 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