{"slug": "i-parsed-559-public-claude-md-files-most-of-what-s-in-them-isn-t-rules", "title": "I parsed 559 public CLAUDE.md files. Most of what's in them isn't rules.", "summary": "An engineer analyzed 559 public CLAUDE.md files and found that 62.9% of the content is documentation rather than actionable rules, with only 43.5% of actual rules being mechanically checkable. The findings suggest that the perceived problem of overly long rules files is often a matter of rules being buried in documentation, and that the distinction between directives and non-directives is a property of language rather than file format. The engineer's tool, RuleReceipt, is available for free and runs locally.", "body_md": "I've been building a tool that checks whether Claude Code actually followed the rules in your CLAUDE.md. Early on I realised I was testing it against one file: my own. So I went and got 559 real ones.\n\nCLAUDE.md, AGENTS.md, .cursorrules, Copilot instructions, Windsurf, Gemini — from PyTorch, Kubernetes, Elasticsearch and a few hundred smaller repos. 23,704 items parsed out of them, no crashes.\n\nTwo things came out of it that I didn't expect.\n\n62.9% of a rules file isn't a rule\n\nDirectory listings. Reference tables. Import examples. Architecture notes. Glob syntax cheatsheets.\n\nAll useful documentation. None of it is telling the agent to do anything. And it's sitting in the same file as the actual rules, competing for the same attention.\n\nSo when someone says their CLAUDE.md is 400 lines, it's usually closer to 150 lines of rules with 250 lines of README stapled on.\n\nThat reframes the \"my CLAUDE.md is too long\" problem. It's often not too many rules. It's rules buried in documentation.\n\nOf the real rules, only 43.5% can be checked mechanically\n\nHere's the split that surprised me more.\n\n**Checkable:**\n\n**Not checkable by any tool, ever:**\n\nThere's no command to inspect for the second group. It's not a limitation of my parser — the information isn't in the transcript. A person has to read it and decide.\n\n56.5% of the rules people actually write fall in that second group.\n\nThe distribution barely moved as the corpus grew\n\nI started with 40 files: 65.4% non-instructions.\n\nAt 559 files: 62.9%.\n\nBetween those two points I added formats the parser had never been tuned on. It moved 2.5 percentage points.\n\nThat's the part I'd actually stand behind. It suggests \"is this a directive?\" is a property of language, not of file format — which matters, because the alternative approach (recognising every way people format\n\nrules) is an infinite list.\n\nWhat I don't know\n\nI don't have a controlled experiment showing longer files perform worse. That's the obvious next question and I haven't run it.\n\nBut if a model is budgeting attention across a long file, it seems worth knowing that most of that file was never telling it to do anything.\n\nThe tool\n\nIt's called RuleReceipt. Free, runs locally, no account:\n\n```\n  npx rulereceipt check\n```\n\nI also published the part where it got things badly wrong — it reported 10 violations on a real session of mine and every single one was false. That write-up is at [https://rulereceipt.dev/postmortem](https://rulereceipt.dev/postmortem), including the wrong turn I took while fixing it.\n\nHappy to answer anything about the method. The corpus was public files only, and the classifier is in the repo.", "url": "https://wpnews.pro/news/i-parsed-559-public-claude-md-files-most-of-what-s-in-them-isn-t-rules", "canonical_source": "https://dev.to/rulereceipt/i-parsed-559-public-claudemd-files-most-of-whats-in-them-isnt-rules-3flo", "published_at": "2026-09-02 05:11:55+00:00", "updated_at": "2026-09-02 05:22:34.149518+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents"], "entities": ["RuleReceipt", "Claude Code", "PyTorch", "Kubernetes", "Elasticsearch"], "alternates": {"html": "https://wpnews.pro/news/i-parsed-559-public-claude-md-files-most-of-what-s-in-them-isn-t-rules", "markdown": "https://wpnews.pro/news/i-parsed-559-public-claude-md-files-most-of-what-s-in-them-isn-t-rules.md", "text": "https://wpnews.pro/news/i-parsed-559-public-claude-md-files-most-of-what-s-in-them-isn-t-rules.txt", "jsonld": "https://wpnews.pro/news/i-parsed-559-public-claude-md-files-most-of-what-s-in-them-isn-t-rules.jsonld"}}