CLAUDE.md Is Advisory, Not Enforced — and That Explains Why Claude Ignores It

A lot of frustration with CLAUDE.md dissolves once you know one detail from the docs: it is delivered to the model as a user message after the system prompt, not as the system prompt itself — and there is, in Anthropic's own words, "no guarantee of strict compliance." It was never a config file the model is bound to. It is context the model weighs, exactly like the rest of the conversation, and like the rest of the conversation it can be outweighed. That is not a bug in your file. That is what the file is.

It is not the system prompt

The mental model most people have — "put it in CLAUDE.md and it becomes a rule" — assumes a level of authority the mechanism does not have:

How CLAUDE.md actually reaches the model

  Not this:   system prompt -> hard rules the model obeys
  Actually:   system prompt
              + CLAUDE.md delivered as a USER MESSAGE after it
              + the rest of the conversation

  Per the docs: "no guarantee of strict compliance."
  It's context to weigh, not a contract to enforce.

Once you see it as advisory user-message text, the behavior everyone complains about stops being mysterious. The model follows it when nothing stronger competes and drops it when something more specific and more recent is in front of it — which is the whole story behind why Claude keeps ignoring your CLAUDE.md. The file is not being overruled by accident; it has no special standing to begin with.

Anthropic points you at hooks for a reason

The tell is in the guidance itself: when you need something actually enforced, the docs send you to hooks, not CLAUDE.md. Hooks are deterministic shell commands the harness runs — a PreToolUse hook can block a forbidden action every single time, no probability involved. That hard guarantee exists precisely because CLAUDE.md cannot provide one. If the official answer to "how do I make sure X always happens" is "don't use the instruction file," that tells you what the instruction file is for: preferences, not guarantees.

Three jobs people ask CLAUDE.md to do

The confusion comes from asking one advisory file to do three different jobs:

Three different jobs, three different tools

  Want the model to KNOW something true about the code?
    -> needs current grounding (an index), not a frozen file

  Want the model to PREFER a convention?
    -> CLAUDE.md is fine; it's advisory and that's okay

  Want to GUARANTEE an action never happens?
    -> hooks: deterministic, harness-run, exit 2 blocks it
    -> CLAUDE.md cannot do this and was never meant to

CLAUDE.md is genuinely good at exactly one of these: expressing preferences and conventions the model should lean toward. It is the wrong tool for hard enforcement (use hooks) and the wrong tool for authoritative current facts about the code (use an index). The frustration comes from using it for the two jobs it cannot do.

The worst job to give an advisory file

The most damaging misuse is treating CLAUDE.md as the source of truth for what the codebase currently is — file paths, module names, service boundaries. That asks an advisory, un-enforced, manually-maintained file to be authoritative and current, two properties it structurally lacks:

Enforcement vs. grounding (both missing from CLAUDE.md)

  CLAUDE.md gives you:
    -> advisory text, weighed against everything else
    -> no enforcement (that's hooks)
    -> no freshness (that's an index)

  So a stale, advisory file is doing the one job —
  authoritative current truth — that it is worst at.

When a stale advisory line about the code does get weighed in, it produces a confident wrong answer — the failure mode in whether CLAUDE.md actually reduces hallucinations. Advisory is fine for "prefer tabs." It is dangerous for "the auth helper lives here," because that needs to be both true and current, and the file guarantees neither.

Where Kognita fits

Use each layer for its actual job. CLAUDE.md for advisory preferences, hooks for hard enforcement — and Kognita for the authoritative, current facts about your code. Kognita maintains a semantic index derived from your source and re-indexed as it changes, retrieved by the agent on demand, so the model's knowledge of the codebase comes from something designed to be true now, not from advisory text someone wrote months ago and hoped would be obeyed. Stop asking the advisory file to be the contract.

Final take

CLAUDE.md is advisory user-message context with no guarantee of compliance — by design, not by defect. It can express a preference. It cannot enforce a rule, and it cannot stay true about a moving codebase, which is why Anthropic routes enforcement to hooks and leaves grounding to you.

CLAUDE.md was never a contract. Enforcement is a hook's job; current truth is an index's job; the advisory file is good only for the preferences in between.