CLAUDE.md Is Documentation Theater

Committing a CLAUDE.md feels like you have grounded your AI. It is in the repo, it is in git history, it has clean headings, a senior engineer wrote it. The box is checked. That feeling — that the work of grounding is done — is the actual problem. A file nobody is required to update, that no build verifies, and that drifts the moment you stop looking at it gives you the appearance of grounding without the substance. And appearance is exactly what gets trusted.

Call it what it is: documentation theater. The performance of being grounded, staged well enough that everyone stops checking whether it is true.

Why it feels like grounding

The file ticks every box that looks like reliability, and not one that is reliability:

Why it feels like grounding

  -> it's in the repo, committed to git (looks official)
  -> Claude read it and nodded (looks effective)
  -> it has headings and code blocks (looks maintained)
  -> a senior engineer wrote it once (looks authoritative)

  None of these are accuracy. They are the SET DRESSING of
  accuracy. The file can satisfy every one of them while being
  six weeks wrong.

Every one of those signals is real and every one is orthogonal to whether the file is correct today. A CLAUDE.md can be committed, well-formatted, written by your best engineer, and confidently describe a module that was deleted last month. The production values are high. The content is wrong. That is theater.

The tells

You can diagnose documentation theater without reading a line of the file. Ask about the forcing functions instead:

The tells of documentation theater

  -> no owner: ask "who keeps this current?" -> silence
  -> no trigger: nothing fails when it goes wrong
  -> no check: no PR reviews it against the diff
  -> no expiry: last edited date is "a while ago"
  -> high trust: everyone assumes it's right because it exists

  A document with no forcing function is a prop, not a control.

If nothing breaks when the document is wrong, nothing will keep it right. This is the same diagnosis we apply to ordinary docs in why your codebase documentation is always out of date: the absence of a forcing function, not a lack of discipline, is what guarantees drift. A control has a forcing function. A prop does not.

Theater is worse than nothing

A missing CLAUDE.md at least signals "verify before you trust." A theatrical one signals the opposite — it broadcasts authority it has not earned, so the agent and the team both lower their guard at the exact moment they should not. That is how a stale file turns into a confidently wrong answer: the wrong fact arrives wearing the costume of a verified one. The false sense of grounding is more dangerous than admitted ignorance.

Substance has a forcing function

The difference between theater and substance is not effort or formatting. It is whether accuracy is enforced by the system or left to goodwill:

Theater vs. substance

  Documentation theater (CLAUDE.md):
    -> looks grounded; accuracy is voluntary and unverified
    -> trusted because it exists, not because it's checked

  Actual grounding (derived index):
    -> accuracy is enforced by the system, not by goodwill
    -> re-derived from source; wrong is not a stable state

Real grounding makes "wrong" an unstable state — something the system corrects automatically — rather than a quiet default that persists until someone notices. When accuracy is derived from the source and refreshed as the source changes, there is no gap between what the document says and what the code is, because there is no separate document to fall behind.

Where Kognita fits

Kognita replaces the prop with a control. Instead of a hand-written file trusted because it exists, it maintains a semantic index derived from your source and re-derived as the code changes, served to the agent on demand. There is no performance of accuracy to mistake for the real thing — accuracy is a property the system enforces, not a chore the team is supposed to remember. Keep CLAUDE.md for the few genuinely stable norms, and stop letting a committed file stand in for grounding it does not provide.

Final take

A committed CLAUDE.md looks like grounding the way a stage set looks like a house. The headings, the git history, the senior author — all real, all beside the point. None of them keep the contents true, and the trust they manufacture is exactly what makes a stale file dangerous.

If nothing breaks when your grounding document is wrong, it is not grounding — it is theater. Real context has a forcing function that keeps it true whether anyone is watching or not.