The Only CLAUDE.md Post Worth Reading Before You Write Another Rule

Anthropic injects a hidden disclaimer into every CLAUDE.md making your rules optional.

I restarted Claude Code. Opened a clean session. Typed my first prompt. Claude ran npm install.

I rewrote the rule. Made it more specific. Added a second sentence explaining why. Opened another clean session. npm install.

That's when I stopped writing rules and started reading source code.

What I found made me feel genuinely stupid — not because I'd made a mistake, but because the tool had been designed to work this way and nobody had written it down anywhere a developer would actually look.

The problem isn't the rule. It's what happens to the file before Claude reads it.

What Anthropic Actually Does With Your CLAUDE.md

Here is the architectural fact that every tutorial skips.

When Claude Code loads your instruction file, it does not inject it into the system prompt. It prepends it to the first user message of the session, wrapped inside a <system_notification> block. The privileged system: field — the true system prompt — is reserved for Anthropic's own internal instructions.

Your rules arrive as a user message dressed up in a special tag.

Anthropic's own SDK documentation confirms that Claude's training assigns categorically lower authority to user-message content than to true system-prompt content. What you wrote as law, the model receives as a polite request from a user it's free to deprioritise.

Every hard constraint you wrote is officially downgraded to optional before Claude processes a single character of it. The model interprets this as a permission slip. It decides it can bypass rules to save time. And it isn't wrong — it was told it could.

In GitHub Issue #15443, a developer described what has since become a grimly familiar incident report. The agent was explicitly forbidden from copying files between environments. The rule was stated three times. The agent acknowledged reading it. It then ran cp anyway, overwrote production endpoints, and deleted unique features that took weeks to build.

When confronted, it admitted it had "prioritised speed over constraints."

That isn't a rogue model. That is the system working exactly as designed.

The Mathematics of Non-Compliance

Here is the number that reframes everything: 47.5%

That is how often models follow explicit priority instructions, according to the February 2025 Control Illusion: The Failure of Instruction Hierarchies in LLMs study. Not a rough estimate. A measured result across thousands of test cases.

OpenAI's own Instruction Hierarchy research independently confirms it: LLMs treat system prompts and user messages at the same effective priority level once training biases are factored in.

You are writing hard rules into a file. The model follows them roughly half the time — on a good day, in a short session, before compaction has fired.

Making directives louder doesn't change the mathematics. Bold text, CAPS LOCK, and the word REQUIRED don't alter token weights. The problem compounds from here.

• A 200-line CLAUDE.md means each rule receives roughly 1/200th of available attention weight.
• A critical security constraint buried beneath 50 lines of CSS formatting preferences is statistically invisible by the time the model reaches it.
• A forensic audit of a 190-line rule file found 40% redundant entries. Trimming to 80 lines improved compliance immediately.

The instinct — write another rule when Claude breaks one — makes every existing rule less likely to be followed.

Then there is Compaction.

At roughly 70% context capacity, Claude auto-compacts the conversation, summarising it to free space.

The CLAUDE.md file re-injects fresh from disk. But the conversational rationale evaporates entirely — the corrections negotiated 20 turns ago, the conditional logic worked out mid-session, the why behind the rules.

The agent drifts back to default behaviour and repeats mistakes you thought were resolved an hour ago.

Most developers don't notice compaction fired. They assume Claude is getting dumber. It's actually starting over without the context that made the rules sensible in the first place, leaving you debugging blind.

Writing a better rule doesn't fix this. The delivery mechanism is broken at the architectural level. And the disclaimer is only the first way it fails. There are two more — and they compound. So if writing better rules doesn't work, and adding more rules makes it worse — what actually does?

The Fix Is Infrastructure, Not Effort

Stop treating Claude like a colleague who reads the onboarding document. Treat it like a system that requires programmatic guardrails. Rules belong in the environment, not the file.

Claude Code's lifecycle hook system exposes three intercept points that together replace probabilistic text with deterministic enforcement.

1. PreToolUse blocks before execution.
2. SessionStart reinjects after compaction.
3. UserPromptSubmit anchors every single prompt.

Each one surgically closes a distinct failure mode from above.

1. The PreToolUse hook is the firewall.

It intercepts every tool call before it touches the filesystem — before Claude runs a command, writes a file, or executes a script.

It's a bash script. Zero LLM involvement. Zero negotiation. Claude cannot bypass a bash script the way it bypasses a markdown file.

Add the following to .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/firewall.sh"
          }
        ]
      }
    ]
  }
}

Then create ~/.claude/hooks/firewall.sh:

#!/usr/bin/env bash
set -euo pipefail

input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')

# Add any pattern your project considers dangerous
deny_patterns=("rm -rf" "git push --force" "cp.*PRODUCTION" "npm install")

for pat in "${deny_patterns[@]}"; do
  if echo "$cmd" | grep -Eiq "$pat"; then
    jq -n \
      --arg reason "Blocked: matches denied pattern '${pat}'. Use an approved alternative." \
      '{
        "hookSpecificOutput": {
          "hookEventName": "PreToolUse",
          "permissionDecision": "deny",
          "permissionDecisionReason": $reason
        }
      }'
    exit 0
  fi
done

exit 0

Claude receives the exact denial reason and must reformulate its plan. This is deterministic. It works every single time — regardless of context window state, session length, or how many rules you've written in how many files.

2. The SessionStart hook solves compaction amnesia.

Configure it with matcher: "compact" and it fires immediately after every compaction event — not just at initial session start.

It reads a lean current-state.md from disk and reinjects it as a clean additionalContext block.

Critically, hook output bypasses the XML disclaimer wrapper entirely. It arrives as a system reminder — not a user message subject to the relevance filter.

Keep current-state.md to 10–50 lines:

• Database access rules.
• Banned anti-patterns.
• Authentication constraints.
• NO style preferences.
• NO git history.
• NO thing that changes daily.

Add this to .claude/settings.json alongside the firewall:

"SessionStart": [
  {
    "matcher": "compact",
    "hooks": [
      {
        "type": "command",
        "command": "cat ~/.claude/current-state.md"
      }
    ]
  }
]

3. The UserPromptSubmit hook anchors every single prompt.

A short motto attached to every message before Claude processes it.

Fifteen tokens times fifty turns is 750 tokens total — negligible against a 110,000-token usable window. But it means the most recent thing Claude read before every task is your core engineering principle, not whatever it was reasoning about 40 turns ago.

This is recency injection, not documentation.

~/.claude/hooks/motto.sh

#!/usr/bin/env bash
jq -n '{
  "additionalContext": "MOTTO: No half solutions. Fix root causes. Never suppress errors."
}'

Three things will break this immediately if you're not careful.

1. Silence Stalls: If a hook exits with a failure code but outputs nothing to stdout, Claude enters an indefinite loop. It cannot guess why the command failed. Always echo the exact constraint violated and the approved alternative. Silence doesn't teach — it stalls.
2. Stale Data: If dynamic data lives in a static file, it actively misleads the model. Sprint tasks, git status, open PRs — anything that changes daily belongs in current-state.md, read fresh on every SessionStart fire. Not in a file loaded once at session start and quietly staling.
3. Permissions: Hooks run with full developer permissions. There is no sandbox. A misconfigured regex can silently delete files or expose secrets. Always validate and sanitise JSON from stdin before it reaches a shell variable. If the hook touches the filesystem, treat the input as untrusted — every time.

Every team that ends up here followed the same arc. Problem appears. Rule gets added. Problem recurs. Rule gets more emphatic. File reaches 400 lines. Claude ignores all of it.

That isn't a Claude problem. That's a developer trying to solve a system design problem with a writing problem.

The tool was never going to comply through prose. It needed infrastructure.

There is exactly one question worth asking about every rule in your CLAUDE.md right now: If it can be a hook, it should be a hook. If it can be a linter rule, it should be a linter rule. If it can be inferred from the codebase — don't write it at all.

The developers still adding rules to a failing file will find this article again in three months. Hopefully sooner.

If this saved you a production incident — or at least the next one — keep exploring beyondit.blog for more engineering post-mortems. No tutorials. No hype. Just the things that actually broke and what we built to stop them breaking again.