How Long Should CLAUDE.md Be? The Point Where It Stops Working

It is the most common CLAUDE.md question on every forum: how long should it be? People want a number — 200 lines, 500, a token budget. The honest answer is that there is no good length, because the file is caught in a vice. Short enough to be reliably followed is too short to be accurate. Long enough to be accurate is long enough to be ignored. You are not choosing a length; you are choosing which failure you would rather have.

The vice, stated plainly

The two failure modes are not on a spectrum you can split the difference on. They are two different walls, and the file hits one or the other:

The CLAUDE.md vice

  TOO SHORT
    -> fits comfortably, every line gets read
    -> but cannot describe a real system: misses modules,
       conventions, the gotchas that actually matter
    -> model fills the gaps by guessing

  TOO LONG
    -> finally accurate enough to cover the system
    -> but now it is skimmed, not read; rules get dropped
    -> eats the context window every turn

  The accurate version and the followed version
  are not the same file.

A 50-line CLAUDE.md gets read in full every time and describes almost nothing about a real system. A 600-line one finally covers the architecture and now gets skimmed — which is its own well-documented failure, the one behind Claude ignoring your CLAUDE.md. The accurate version and the followed version are not the same file.

The file only grows in one direction

Worse, the pressure is asymmetric. Every incident, every new service, every convention adds a line. Almost nothing ever removes one, because deleting a rule feels like inviting the bug it prevented. So the file ratchets upward over time:

Why it only grows in one direction

  Every incident adds a line:   "don't do X, it broke prod"
  Every new service adds a note: "payments-core lives in..."
  Every convention adds a rule:  "always use the X helper"

  Nobody ever removes a line. Deleting feels risky.
  So CLAUDE.md ratchets upward, past the point where
  it was followed, toward the point where it is ignored.

Whatever length you pick today, the file does not stay there. It grows past the point where it was comfortably followed and keeps going. The question is not "what length should it be" but "what length will it inevitably become" — and the answer is: too long.

Length is the wrong lever

The reason there is no good length is that length is the wrong variable. The real problem is that a single static document is being asked to answer every possible question with the same fixed content. A question about auth and a question about the build pipeline pull from the same block of text, most of which is irrelevant to either. You cannot tune that with length. A shorter file is more relevant per line and less complete; a longer one is more complete and less relevant per line. Neither escapes the fact that the file is loaded whole, every time, regardless of the question.

This is the same ceiling as why context windows are never enough: adding more standing text does not improve retrieval. It just changes which problem dominates.

What scales when a document can't

The way out is to stop sizing a document and start querying an index. An index has no fixed length — it can hold the entire codebase — and it returns only the slice each question needs:

What scales when a document can't

  A document:
    -> one length for all questions
    -> must choose: complete (long) or followed (short)
    -> the wrong half is always loaded

  An index:
    -> no fixed length; holds the whole codebase
    -> returns only the slice each question needs
    -> short in the prompt, complete underneath

With retrieval, the "file" is effectively complete and the prompt stays short, because completeness lives in the index and relevance decides what reaches the model. The vice disappears — not because you found the magic length, but because you stopped depending on one.

Where Kognita fits

Kognita keeps the full, current representation of your repositories in a semantic index and serves only the relevant portion to the agent per query through MCP. Completeness and concision stop being in tension: the index is complete, the prompt is concise. The right answer to "how long should CLAUDE.md be" is to keep it short and global on purpose — a handful of genuine team-wide norms — and let an index carry the detailed, per-question codebase knowledge that no single length of file could.

Final take

If you are searching for the optimal CLAUDE.md length, you are optimizing a tradeoff with no good point on it. Short loses accuracy; long loses obedience; and the file drifts toward long no matter where you start.

There is no right length for CLAUDE.md, because the problem was never length. Keep it short and global, and put the detail in an index that returns only what each question needs.