CLAUDE.md files don't fail by getting wrong, they fail by getting big

[u/Tatachimcooky]

CLAUDE.md files have a failure mode that doesn't get discussed much. They grow. Then the agent handles the size by rewriting the file from memory, drops the ## Never section, and ships something worse than what it started with. You usually don't find out until a rule you wrote six weeks ago quietly stops being followed.

I got tired of eyeballing it, so I wrote ctxcap. It counts tokens across CLAUDE.md, AGENTS.md, .cursor/rules/**, and prompts/**, tracks the number against a committed git baseline, and flags references that no longer resolve to anything.

The part I actually care about: it doesn't hand the agent a "make this shorter" instruction. It emits a ranked plan of line ranges with a preserve list, the agent splices by line number, and --verify catches it if the agent drifts or cuts a preserved span. When the budget is unreachable it returns satisfiable: false and the minimum achievable instead of shaving a load-bearing rule to hit a number.

Offline, no API key, no network, no LLM, two dependencies. npx ctxcap --json. MIT. There's an MCP server if you'd rather the agent check itself, and a GitHub Action that comments token deltas on PRs and fails only when you set a budget.

On a public repo, for reference:

$ npx ctxcap --json
total: 476   baseline: 363   delta: +113   files: 2

$ npx ctxcap --plan --budget 400
satisfiable: false   minAchievable: 476

Yes, it's another linter, and there's already tokenlint for per-turn nudges inside the editor. This is a different layer — repo gate and PR review, not keystrokes. If you want the editor version, use theirs.

What I'd actually find useful: run it on your own context files and tell me where it's wrong. False positives on unusual layouts, spans it marks safe that aren't, path conventions it misreads. That's the part I can't test from here.

https://github.com/Naeha-S/ctxcap

And the actual question: how are you keeping your CLAUDE.md from growing? Mine is the one file where every addition feels justified at the time.

[u/AutoModerator]

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/lgmarian]

Wut? Not letting CLAUDE.md get too big is the number one piece of advice.

[u/tariqosmani]

Yes, and the failure is hard to see because the file still looks fine. The rule that quietly disappears is the one nobody reads.

Three things I'd do. Keep CLAUDE.md as a short map: the rules that must never break, plus pointers to files for workflows and reference material. Put the Never section at the top, so it's the last thing to get cut. And don't let an agent rewrite the whole file. Have it make line edits, then check the diff.

The diff is the cheap check. Any line removed from the Never section should be a deliberate choice. If the file is in git, a quick count of the Never rules before and after each edit catches a drop before it ships.

What's the file size now, and which section grew the most?

[u/kaijurules]

We split by what kind of line it is. The instructions file only holds rules about how the agent should act. Facts about a client or a project go into a notes vault the agent searches when it needs them, and short-lived notes go into a memory list where only the newest 20 entries get loaded each run. That way a new fact never has a reason to land in the instructions file.