Create or audit a CLAUDE.md

CLAUDE.md

Before You Start

• principles/02-dense-not-brief.md

  — the rule that drives

  CLAUDE.md

  length. Load-bearing, not pad.

• skills/meta/create-or-audit-claude-md/templates/CLAUDE.md

  — the annotated root skeleton with required sections.

• skills/meta/create-or-audit-claude-md/templates/CLAUDE.subdir.md

  — the subdir skeleton + the four trigger criteria.

• skills/meta/create-or-audit-claude-md/lib/validate.sh

  — the mechanical gate.

Mode 1 — create a CLAUDE.md

Step 1: discover the codebase

# Top-level shape
ls -la
find . -maxdepth 2 -type d -not -path '*/node_modules*' -not -path '*/.git*'

# Build/test/lint commands (look in all the usual places)
cat package.json 2>/dev/null | jq '.scripts // {}'
cat pyproject.toml 2>/dev/null | grep -A 20 '\[tool\.' | head -40
cat Makefile 2>/dev/null | grep -E '^[a-zA-Z_-]+:'
cat justfile .justfile 2>/dev/null
ls .github/workflows/ 2>/dev/null

# Entry points
git log --pretty=format: --name-only -200 | sort | uniq -c | sort -rn | head -30

Step 2: identify subsystems

src/

apps/

packages/

services/

lib/

• What does it own?
• How does it communicate with siblings?
• What language/framework does it use?

Step 3: extract the "things to know"

CLAUDE.md

# Recent bug fixes reveal invariants
git log --oneline --all | grep -iE 'fix|bug' | head -30

# ADRs if they exist
ls docs/adr docs/decisions docs/arc42/decisions 2>/dev/null

# "Do not edit this" and "DANGER" comments in the code
grep -rniE 'DO NOT|DANGER|CAREFUL|WARNING|HACK|FIXME|TODO' --include='*.py' --include='*.ts' --include='*.js' --include='*.go' --include='*.rs' | head -30

Step 4: write the file using

root.md.template

skills/meta/create-or-audit-claude-md/templates/CLAUDE.md

• Quick Reference — real commands that actually run. If

  pnpm test

  doesn't exist, don't list it.
• Architecture — the longest section. 2–3 paragraphs overview + directory tree + per-subsystem deep-dives.
• Patterns and Conventions — only things a linter doesn't catch (principle 03).
• Things to Know — gotchas with structure: what happens → why → what to do. These are pure value for the agent.
• Security-Critical Areas — a short, honest list. Lying here will erode trust.

Step 5: create subdirectory CLAUDE.md files

CLAUDE.md

skills/meta/create-or-audit-claude-md/SKILL.md

Mode 2 — audit an existing CLAUDE.md

Step 1: run the validator

bash skills/meta/create-or-audit-claude-md/lib/validate.sh CLAUDE.md

Step 2: five quality gates

grep -oE '`[a-zA-Z_./-]+/[a-zA-Z_.-]+`' CLAUDE.md | sort -u | while read p; do
  path=$(echo "$p" | tr -d '`')
  [ ! -e "$path" ] && echo "STALE: $p"
done

never

don't

do not

instead

use X instead

prefer

CLAUDE.md

Step 3: report

## CLAUDE.md Audit: {path}

### Verdict: APPROVE | REVISE | REJECT

### Gate results
...

### Stale references (must fix)
{List of paths that no longer exist}

### Duplicated tooling rules (remove these — point at the tool)
...

### Missing sections
...

### Proposed additions to "Things to Know"
{From your discovery in step 2}

Verify

# Validator passes
bash skills/meta/create-or-audit-claude-md/lib/validate.sh CLAUDE.md
# Expected: VERDICT: PASS

# No stale file references
grep -oE '`[a-zA-Z_./-]+/[a-zA-Z_.-]+`' CLAUDE.md | tr -d '`' | while read p; do
  [ ! -e "$p" ] && echo "STALE: $p"
done
# Expected: empty output

Common Mistakes

`src/api/routes.ts` — see this for the pattern.

.eslintrc.json

ruff.toml

x

y

src/lib/y.ts

What doesn't belong in CLAUDE.md

• Rules already enforced by tooling. If ESLint catches it, don't restate it (principle 03).
• Temporary state. Current sprint goals, "in-progress" features. That's issue-tracker territory.
• Long tutorials. If a walkthrough is >20 lines, it's a skill, not ambient context.
• Embedded code snippets over 10 lines. They rot. Reference the file instead (principle 04).