← Penloom

Your CLAUDE.md is too long — and that's why Claude Code ignores it

CLAUDE.md is an instruction budget, not a wishlist. Spend it like one.

Everyone hits the same wall with Claude Code. You add a rule to CLAUDE.md. It works. You add ten more. They mostly work. You add forty more — and now Claude is cheerfully ignoring the rule you care about most, the one that's been sitting there since day one. So you make it LOUDER, in caps, with three exclamation points. It still gets skipped.

The instinct is to write more. The fix is almost always to write less. Here's why, and what to do instead.

Instruction-following has a budget, and you're overdrawn

This is the part most CLAUDE.md guides skip. Frontier models reliably follow on the order of 150–200 instructions at once — and adherence to any single rule drops as you stack more on top of it. It isn't a cliff; it's a slow tax. Every line you add makes every other line a little less likely to be honored.

Now subtract what you don't control: Claude Code's own system prompt already spends a chunk of that budget before your file is even read. So the working budget for your project rules is smaller than the headline number — and a sprawling 300-line CLAUDE.md isn't 300 rules followed, it's maybe the first 150 followed well and the rest treated as ambience.

The mental model that fixes everything downstream: CLAUDE.md is a budget, not a wishlist. You are not writing documentation. You are spending a scarce attention allowance, and every line competes with every other line.

The test for every line: would you bet $5 it's followed?

Go through your file line by line and ask one question of each rule: would I bet money this fires every time it's relevant? Three outcomes:

• Yes, and it's load-bearing — keep it. This is what the budget is for.
• Nice to have, but I wouldn't bet on it — cut it, or move it to a referenced file (below). It's diluting the rules you would bet on.
• It absolutely must happen every time — then it doesn't belong in CLAUDE.md at all. Make it a hook.

That third category is the one people get wrong, so let's be concrete about it.

Advisory vs. deterministic: know which one you need

A CLAUDE.md rule is a request. A good model honors it most of the time — call it ~80%. For style preferences, naming conventions, "explain before you refactor," 80% is completely fine; the cost of a miss is low.

But some rules can't tolerate a 1-in-5 miss: never commit secrets, never touch production.env, always run the test suite before declaring done. For those, prose is the wrong tool no matter how forcefully you phrase it. You want a hook — a shell command Claude Code runs automatically at a fixed point in its lifecycle. A hook doesn't ask the model to cooperate; it fires deterministically, every time, whether the model "felt like it" or not.

Here's the graduation in practice. The CLAUDE.md version — advisory, ~80%:

# in CLAUDE.md
- Never edit .env files or anything under .git/. Never commit secrets.

The hook version — deterministic, 100%. A PreToolUse hook that blocks the write before it happens:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "node -e \"const p=process.env.CLAUDE_TOOL_INPUT_FILE_PATH||''; if(/(^|\\/)\\.env|(^|\\/)\\.git\\/|secrets/i.test(p)){console.error('Blocked: protected path '+p);process.exit(2)}\""
      }]
    }]
  }
}

Exit code 2 tells Claude Code the action was refused and feeds the reason back to the model, so it adapts instead of failing silently. The rule it replaced can now leave CLAUDE.md entirely — you just bought back a line of budget and upgraded a must-happen rule from 80% to 100%. That's the trade you're looking for on every critical line.

Every rule needs a reason — or it doesn't generalize

"Use tabs, not spaces" is a rule that applies exactly once, literally. "Use tabs, not spaces — our linter rejects spaces and the build fails" is a rule the model can reason from: it now knows the underlying constraint and will make the right call in situations you never spelled out. A rule with a reason generalizes. A bare command gets followed only in the exact case you wrote, and quietly dropped the moment the context shifts an inch. Reasons aren't padding — they're what makes a rule worth its place in the budget.

Progressive disclosure: keep the hot path short

You don't actually have to choose between "short file" and "thorough guidance." Keep CLAUDE.md to the rules that apply to most tasks, and push the rest into focused files you reference by path:

# CLAUDE.md (the always-loaded hot path — keep it lean)
- Run `npm test` before declaring any task done.
- API conventions live in docs/api-guidelines.md — read it before touching routes/.
- DB migrations: follow docs/migrations.md exactly.

Claude pulls docs/migrations.md into context only when it's actually doing a migration. The detailed guidance still exists, fully — it just isn't taxing your budget on the 90% of tasks where it's irrelevant. Your CLAUDE.md stays a tight, high-adherence core; the depth lives one hop away, loaded on demand.

The 20-minute audit

Open your CLAUDE.md right now and do this pass:

• Count the lines. Past ~150 and climbing? That alone explains a lot of "it ignored me."
• Delete every rule you wouldn't bet $5 on. Be ruthless. A diluted file follows nothing well.
• Find the must-happen rules and make them hooks. Secrets, destructive commands, test-before-done. Move them out of prose.
• Add a reason to every surviving rule. If you can't articulate why, you don't need the rule.
• Move task-specific depth into referenced files. Keep the hot path lean.

Almost everyone who does this honestly ends up with a shorter file that Claude follows more reliably. That's not a paradox — it's the budget working as intended.

---

The one-paragraph version

Instruction-following is a scarce budget, not a wishlist. Models reliably follow ~150–200 rules and adherence drops as you pile on more, so every line in CLAUDE.md should be one you'd bet money on. Cut what you wouldn't bet on, give every survivor a reason so it generalizes, push task-specific depth into referenced files, and graduate the must-happen rules out of advisory prose into deterministic hooks. Shorter file, higher adherence.

New to this? Start with the free field guide — seven reliability rules and three paste-able Claude Code guardrails, no email required.