Clogmeter
Check your CLAUDE.md against the 200-line target → Paste it into the free CLAUDE.md token counter to see its lines and tokens. Runs in your browser; nothing is uploaded.

Home · Guides · Monday 16 Nov 2026

Too many gotchas in CLAUDE.md? Delete, enforce, scope or keep

When most of a CLAUDE.md is gotchas, don’t trim it line by line. Sort every gotcha into one of four piles: delete it (no longer true, or a one-off), enforce it with a test, lint rule, hook or permission to catch or block it, scope it to the folder or files it’s about so it only loads there, or keep it in the root file because it really applies to every task. In the worked example below, 20 gotchas became 5, and the always-on section went from 561 tokens to 100.

The question comes from an r/ClaudeCode thread (13 Nov 2026): “75% of my CLAUDE.md is taken up by Gotchas alone. What are your best practices?” The replies agreed on the shape of the answer — fix the cause, move area-specific notes next to the code, block the dangerous ones with hooks — and this guide turns that into a repeatable pass.

No invented benchmarks. Loading behaviour is from Anthropic’s Claude Code memory docs and permissions docs (checked 16 Nov 2026). Token figures were measured with Clogmeter’s o200k_base tokenizer on the example file below.

Why gotchas pile up (and why it hurts)

The four piles

Ask these questions of each gotcha, in this order. Stop at the first “yes”.

Question If yes Where it goes
1. Is it no longer true, a one-off incident, or something a check already catches? Delete Nowhere. Git history keeps it if you need it back.
2. Could a machine stop the mistake? Enforce A test, lint rule, package script, pre-commit or PreToolUse hook, or a permissions.deny rule such as Read(./.env) or Edit(/src/generated/**). Then remove the line.
3. Does it only matter in one folder or file type? Scope A CLAUDE.md in that folder, or a .claude/rules/*.md file with paths: frontmatter. Subdirectory CLAUDE.md files below your launch directory load when Claude works there; path rules load for matching files.
4. Is it about your machine, not the project? Scope (user level) ~/.claude/CLAUDE.md or ~/.claude/rules/, so every project shares it and the repo file stays about the repo.
5. Does it apply to almost every task, and can’t be checked? Keep The root CLAUDE.md, one line each, with a short reason.

Worked example: 20 gotchas down to 5

We wrote an illustrative 20-item gotchas section for a TypeScript web app (pnpm, Postgres, Stripe, a legacy/ package, Playwright) and sorted it with the questions above:

Pile Gotchas What replaced them
Delete (2)“Port 5173 busy → kill old Vite”; “add routes to openapi.yaml”Nothing. The first is trivia; the contract test already fails on the second.
Enforce (8)Migrate before tests; don’t edit src/generated/; don’t import legacy-utils; never commit .env; no live Stripe keys in fixtures; install Playwright browsers; Node 20+; no anyA pretest script, permissions.deny rules, ESLint no-restricted-imports and no-explicit-any, a secret-scanning pre-commit hook, an explicit browser-install setup step, a CI runtime-version check (an engines declaration alone may only warn).
Scope (4)Two legacy/ rules (CommonJS, old logger); webhook idempotency; formatInZone() in billinglegacy/CLAUDE.md, and .claude/rules/payments.md with paths: ["src/payments/**", "src/billing/**"].
User level (1)“The shell is zsh, so variables don’t word-split”~/.claude/CLAUDE.md
Keep (5)pnpm only; store UTC; never change /api/v1 shapes; lowercase emails; done means tests and lint passStayed in the root file, rewritten as one line each.
Root gotchas section Lines Tokens (o200k_base)
Before: 20 gotchas, mostly two-sentence paragraphs21561
After: 5 one-line gotchas6100

The four scoped rules didn’t vanish; they now load only when Claude touches legacy/, payments or billing. After checks are wired into the actual workflow and tested against the old mistakes, those eight warnings need not stay in the prompt. Hooks and checks can have configuration gaps: a file-tool deny rule is not a complete shell sandbox, and a pre-commit hook is not a substitute for server-side secret scanning. The worked section shrank by more than 80%; that is an illustrative section-size reduction, not a measured reduction in total session tokens. User-level rules still load, and scoped rules consume context when triggered.

How to write the ones you keep

Stop the pile coming back

  1. New gotchas go to the narrowest home first. Folder file, path rule, or a check. The root file is the last resort, not the default.
  2. Fix the cause when you can. If a gotcha describes a bug in shared code, fix or test the code path and skip the warning.
  3. Audit monthly. Claude Code’s /doctor prompt-audit (v2.1.283+) reports outdated or conflicting instructions and proposes edits without changing files. For any tool, paste the files into Clogmeter to see token weight and flag duplicate or always/never conflicting rules.
  4. Watch what agents append. If an agent adds gotchas for you, review those diffs like code. Claude Code’s auto memory is separate (MEMORY.md, first 200 lines or 25KB loaded each session) and needs the same occasional prune.

The same four piles work outside Claude Code: nested AGENTS.md files scope rules by folder for Codex and Cursor, and Cursor Auto Attached project rules with globs attach for matching files. Check each tool’s discovery behaviour; their scoping mechanisms are not interchangeable.

Open Clogmeter and weigh your instruction files → Free, browser-only. Export a trimmed copy when you are done.

No spam. Unsubscribe anytime. We never share your email.