Does CLAUDE.md Actually Reduce Hallucinations? Not the Way You Think

The pitch for CLAUDE.md is straightforward: ground the model in real facts about your project and it stops making things up. And it works — for as long as the file is correct. The honest, complete answer to "does CLAUDE.md reduce hallucinations" is: yes, while it is true, and then it does the opposite. A grounding document does not have a constant effect on hallucination. It has a half-life.

Yes — while it stays accurate

Give the model the actual module names, the real file paths, the conventions your team uses, and it has anchors to reason from instead of plausible-sounding guesses. That is real grounding and it really does cut hallucination in the early life of the file. It is worth saying plainly, because the rest of this post is a caveat and the caveat is not "CLAUDE.md is useless."

What CLAUDE.md does to hallucination over time

  WHILE ACCURATE (day 0 to ~week 2):
    -> gives the model real anchors: names, paths, conventions
    -> fewer invented APIs, fewer wrong imports
    -> genuinely reduces hallucination. This part is real.

  ONCE STALE (the rest of the file's life):
    -> the anchors now point at code that changed
    -> the model trusts them instead of checking
    -> it produces confident WRONG answers it wouldn't have
       made with no file at all
    -> net effect flips from reducing to manufacturing

The mechanism that reduces hallucination in week one is the same mechanism that manufactures it in week eight. The model trusts the file. While the file is true, trusting it is good. Once the file is stale, trusting it is exactly the problem — and the model has no way to tell which phase it is in.

A stale file changes the kind of wrong

The subtle part is that a stale CLAUDE.md does not just fail to help. It converts a visible, catchable failure into an invisible one:

Two ways to be wrong

  Ungrounded model:        "I'm not sure where auth lives"
    -> hedges, asks, or searches before answering
    -> the uncertainty is visible and catchable

  Stale-grounded model:    "auth lives in app/auth/helpers.py"
    -> states it as fact (the file said so)
    -> no hedge, no search; you can't tell it's wrong
    -> a hallucination wearing the badge of grounding

An ungrounded model that says "I'm not sure" triggers a check. A stale-grounded model states the wrong path as fact and triggers nothing. As we argue in the failure mode worse than hallucination, confident wrong is more expensive than admitted unsure, because it removes the signal you would have used to catch it. The file did not reduce the error rate; it disguised the errors.

The real question is whether the grounding stays true

So "does grounding reduce hallucination" is the wrong question. Grounding reduces hallucination; the question is whether your grounding stays true long enough to keep doing so. For a static file on a moving team, the answer is no — accuracy decays, and the anti-hallucination benefit decays with it, eventually going negative. This is the distinction at the heart of context grounding as the real fix for hallucination: grounding only works if it is current.

What keeps the reduction

To hold the reduction past the file's honeymoon, the grounding has to stay accurate without depending on anyone remembering to update it:

What actually keeps the reduction

  CLAUDE.md:
    -> reduces hallucination only while it stays true
    -> accuracy decays; the benefit decays with it

  Always-current index:
    -> grounding stays true because it re-derives from code
    -> the reduction holds past week two, past the refactor

An index re-derived from the source does not have a honeymoon that ends. The anchors it gives the model are the current names, the current paths, the current patterns — so the early-life reduction in hallucination is the steady state, not a phase. The benefit you measured in week one is the benefit you still have after the refactor.

Where Kognita fits

Kognita is grounding designed to stay true: a semantic index derived from your code and re-indexed as the code changes, retrieved by the agent on demand. It delivers the same anti-hallucination effect a fresh CLAUDE.md gives you on day one — real names, real paths, real structure — and keeps delivering it after the file would have drifted into confidently wrong territory. The reduction does not have a half-life, because the grounding does not.

Final take

Does CLAUDE.md reduce hallucinations? Yes — and then, once it goes stale, it manufactures them, trading honest uncertainty for confident wrong answers sourced from authoritative system-prompt text. The grounding works only as long as it is true.

Grounding reduces hallucination only while it stays accurate. A static file's accuracy decays; an index re-derived from the code does not — so only one of them keeps the benefit.