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)
- Every gotcha is a scar from one bad session. Adding a line is the quickest fix after a mistake, and nobody ever schedules removing one.
- The root file loads every session. Anthropic says to target under 200 lines per
CLAUDE.md, because longer files consume more context and reduce adherence. A gotcha about the billing module costs tokens while you fix CSS. - Prose is not enforcement. The docs say Claude treats
CLAUDE.mdas context, not enforced configuration. A “never edit X” line can still be skipped; a permission deny rule is checked by the client for the tools it covers. - Old gotchas contradict new ones. “If two instructions contradict each other, Claude may pick one arbitrarily.” Gotcha lists are where those contradictions hide.
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 any | A 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 billing | legacy/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 pass | Stayed in the root file, rewritten as one line each. |
| Root gotchas section | Lines | Tokens (o200k_base) |
|---|---|---|
| Before: 20 gotchas, mostly two-sentence paragraphs | 21 | 561 |
| After: 5 one-line gotchas | 6 | 100 |
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
- One line, with the reason. “pnpm only:
npm installrewrites the lockfile and breaks CI.” The reason helps the model apply it and tells you later whether the line can go. - State the rule, not the story. “We had a bug in March where invoices showed the wrong day” is a story. “Store UTC; convert only in the UI” is the rule.
- Merge near-duplicates. Two gotchas about the same thing (“use
log()” and “inlegacy/useoldLogger”) become one rule in one place, or they start to contradict. - Date it if it might expire. A short date in a comment makes the next prune quick.
Stop the pile coming back
- 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.
- 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.
- 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. - 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.