The Most Expensive File in Your Repo Runs on Every Single Turn

The consensus that formed over 2026 is that context engineering replaced prompt engineering as the real leverage point — the model is rarely the bottleneck, the context almost always is. And the most-loaded piece of context in any repo is the one nobody audits: CLAUDE.md (or AGENTS.md). It goes into every session, so you pay its token cost every turn and you inherit its mistakes on every run. A good one is the highest-leverage file you own. A bloated, stale one is a tax you forgot you're paying.

Three things make these files quietly hurt, and all three are checkable. So we wrote a small linter, context-lint, that checks them.

1. Bloat past what the model can actually follow

It's tempting to pour every rule, convention, and one-off into CLAUDE.md. But frontier models follow roughly 150–200 instructions with reasonable consistency — past that, later instructions get silently dropped. So a 300-rule CLAUDE.md doesn't make the agent 300-rules-disciplined; it makes the agent follow some of them, unpredictably, while you pay for all 300 in tokens on every turn.

context-lint counts the instructions (the bullets, numbered items, and short directive sentences the model is meant to obey) and flags it against that ceiling:

context-lint — CLAUDE.md  (261 instructions · ~4,092 tokens/session)

  ● HIGH  261 instructions — well past the ~150 a model follows reliably; later ones get silently dropped
          move task-specific / one-off rules out; link to docs/ instead of inlining.
  ● WARN  ~4,092 tokens loaded into every session (≈2,872 words)
          every turn pays this. Keep CLAUDE.md lean; push detail to skills / docs/.

The fix the research keeps landing on is progressive disclosure: keep CLAUDE.md to the small set of universally-applicable rules, and push everything else into docs/ (linked) or skills (loaded only when the task matches). Task-specific instructions belong in your prompt, not in a file every session re-reads.

2. Stale references that send the agent chasing ghosts

A CLAUDE.md ages worse than code, because nothing breaks when it goes wrong. It says "the parser lives in src/legacy/old-parser.js" long after that file was deleted and moved — and now the agent, trusting its own context, goes looking for code that isn't there, or worse, recreates it. This is the failure mode that makes a stale context file actively harmful rather than merely wasteful.

context-lint pulls the path-like references out of the file and checks each one against the repo:

  ● HIGH  2 referenced path(s) don't exist — the agent will chase code that isn't there
          fix or remove: `config/secrets.yaml`, `src/legacy/old-parser.js`

It only flags things that genuinely look like file paths (a slash and a real-ish extension), and it confirms the existing ones are fine — a path that resolves doesn't get nagged about. A green run means your context file still describes the repo it's sitting in.

3. The one thing it's most costly to omit

The single most useful thing you can put in CLAUDE.md is how to build and test — it's the difference between an agent that verifies its own work and one that guesses. So a context file that has a dozen style rules but never says npm test is missing the highest-value line. context-lint flags that too:

  ● INFO  no build/test/lint command found
          the highest-value thing to put in CLAUDE.md is how to build and test.

(One small bug worth mentioning, because it's the kind that bites every linter: a naive substring check thought a heading like "NoTesting" contained "test" and decided a test command was present. The fix is whole-word matching — and a test pinning exactly that, so the check stays honest.)

Using it

context-lint                 # audits ./CLAUDE.md and ./AGENTS.md
context-lint path/to/CLAUDE.md

Run it in CI, or as a pre-commit on the context file itself. It exits non-zero on findings, so a CLAUDE.md can't quietly rot — the moment it bloats past the ceiling or starts pointing at deleted files, the check goes red.

The honest limits

It measures shape, not wisdom. It can tell you a file is 4,000 tokens of 261 instructions; it can't tell you those are the right instructions, or that a lean file says the useful things. "References a real path" isn't "describes it correctly." Treat it as the smoke detector for the failure modes that are mechanical — too long, out of date, missing the basics — not as an editor for the prose. The judgment of what belongs in the agent's always-on context is still yours; this just keeps the file from drifting into the three states that reliably make it worse.

The real lesson

Every other file in your repo earns its keep by being run when it's needed. CLAUDE.md is run every single turn, needed or not — which makes it the one file where bloat and staleness compound instead of sitting harmlessly. The move that pays off is to treat it like the high-traffic surface it is: keep it short enough that the model actually follows it, current enough that it doesn't mislead, and pointed at how to build and test. context-lint is one command that tells you whether it still is.

We build and run autonomous agent fleets on Claude Code in production. If you're tuning the context layer, talk to us.

---

Get the tool → context-lint in agent-ops — open source (MIT), a single dependency-free script, part of our toolkit for running coding agents in production.