DEV Community: Penloom Studio

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

Penloom Studio — Sat, 27 Jun 2026 18:15:51 +0000

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.

If you want CLAUDE.md templates that already follow this — plus five ready-to-paste hooks (including the secrets guard above), subagents, and slash-command skills — I put together a Claude Code Power-User Pack. And if you're just getting started, the free field guide covers seven reliability rules and three paste-able guardrails, no email required.

What's the one rule your CLAUDE.md keeps ignoring? Reply and tell me — the patterns repeat more than you'd think.

Why your AI agent is flaky — and 7 rules that make it reliable

Penloom Studio — Sat, 27 Jun 2026 16:44:23 +0000

You built an AI agent. In the demo it was magic. In the wild it loops, hallucinates a tool call, "forgets" the format you asked for twice, and occasionally does something mildly alarming with your filesystem.

Here's the uncomfortable truth after shipping a lot of these: a flaky agent is almost never a model problem. It's a specification problem. The model is doing exactly what your prompt, your tools, and your control loop told it to do — which turns out to be far less than you thought you said.

Below are seven rules that consistently move an agent from "cool demo" to "I trust this on real work." None of them require a bigger model. Three of them are paste-able guardrails for Claude Code specifically.

1. Make the success criteria machine-checkable, not vibes

"Summarize this well" is unfalsifiable. The agent can't tell when it's done, and neither can you. Replace every vibe with something a script could check:

❌ "Return a good summary."
✅ "Return 3–5 bullet points, each ≤ 20 words, each starting with a verb. Output only the bullets, no preamble."

The reliability win isn't the format — it's that failure becomes detectable. If you can write an assert for the output, you can build a retry around it. If you can't, you have no idea how often it's wrong.

2. Give tools narrow contracts and loud errors

Most "the agent called the wrong tool" bugs are actually "the tool description was ambiguous" bugs. A tool named search that sometimes means web search and sometimes means database lookup will get confused. Two rules:

One tool, one job, one unambiguous name (search_web, not search).
When a tool fails, return why in plain language the model can act on: "error: 'date' must be YYYY-MM-DD, got '6/27'" beats a stack trace or a silent null. The model can recover from a sentence; it cannot recover from undefined.

3. Bound the loop — always

Every autonomous agent needs three hard limits or it will eventually run forever: a max step count, a wall-clock timeout, and a no-progress detector (if the last two actions are identical, stop). The model will not reliably stop itself. This is your job, in code, outside the prompt.

4. Prefer deterministic guardrails over polite requests

Anything you put in the prompt is a request. The model usually honors it. "Usually" is not a security model. If an action is dangerous or irreversible, gate it in code, not in English.

Concretely, in Claude Code you can do this with hooks — deterministic scripts that run before a tool call and can block it. Here are the three I put in almost every project.

Guardrail A — block edits to sensitive paths. A PreToolUse hook that refuses any write to .env, .git/, or secrets:

{
  "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 blocked and feeds the reason back to the model — so it adjusts instead of silently failing.

Guardrail B — never let "rm -rf" through. A PreToolUse matcher on Bash that hard-fails on obviously destructive commands:

{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    "command": "node -e \"const c=process.env.CLAUDE_TOOL_INPUT_COMMAND||''; if(/rm\\s+-rf|git\\s+reset\\s+--hard|:\\(\\)\\{/.test(c)){console.error('Blocked destructive command');process.exit(2)}\""
  }]
}

Guardrail C — auto-format after every edit, so the agent's output is consistent without you asking each time:

{
  "matcher": "Edit|Write",
  "hooks": [{ "type": "command", "command": "prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true" }]
}

The pattern that matters here: the model proposes, deterministic code disposes. Hooks run whether or not the model "felt like" honoring an instruction.

5. Make state explicit and external

If your agent's "memory" is just the growing chat transcript, it will drift — early instructions get diluted, and cost climbs every turn. Keep the durable facts (the task, the constraints, what's been done) in a small structured object you re-inject each step, and let the transcript be disposable. An agent that re-reads its own goal every loop stays on task far longer than one trusting a 40-message context to hold.

6. Test it like software, because it is

You wouldn't ship a function with zero tests; don't ship an agent with zero either. Build a tiny eval set — even 10–15 representative inputs with checkable expected properties (rule #1 makes this possible). Run it on every prompt change. The first time a "harmless" prompt tweak silently breaks 3 of 12 cases, you'll understand why this is the highest-leverage 30 minutes in the whole project.

7. Fail loudly to a human, never silently to the user

When the agent is uncertain or a guardrail trips, the worst outcome is confidently shipping a wrong answer. Design an explicit "I'm not sure, here's why" path. A reliable agent that occasionally says "I couldn't verify X, stopping" earns more trust than a confident one that's wrong 5% of the time on work that matters.

The one-paragraph version

Reliability is not a model you buy; it's a discipline you impose. Make success checkable (#1, #6), make tools unambiguous and loud (#2), bound the loop (#3), enforce the dangerous stuff in code rather than in prose (#4), externalize state (#5), and fail loud to a human (#7). Do those and an ordinary model behaves like a dependable one.

If you want this as a printable checklist plus three more ready-to-paste Claude Code guardrails, I wrote a free field guide — no email required: Ship a Reliable AI Agent — the Free Field Guide. It's the 10-minute version of everything above.

What's the failure mode that bit you hardest building agents? I collect these — the patterns repeat more than you'd think.