--- title: Your CLAUDE.md File Is Getting Too Long. Here's What the... description: CLAUDE.md files (and equivalents like agents.md) tend to grow uncontrollably over time - a study of nearly 2,000 repositories found these instruction files... canonical: https://daily.dev/posts/your-claude-md-file-is-getting-too-long-here-s-what-the-research-says--btwbkgt7u twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: Your CLAUDE.md File Is Getting Too Long. Here's What the Research Says. | daily.dev og:description: CLAUDE.md files (and equivalents like agents.md) tend to grow uncontrollably over time - a study of nearly 2,000 repositories found these instruction files... og:url: https://daily.dev/posts/your-claude-md-file-is-getting-too-long-here-s-what-the-research-says--btwbkgt7u og:image: https://api.daily.dev/og/posts/BtWbkGT7U.png og:image:alt: Your CLAUDE.md File Is Getting Too Long. Here's What the Research Says. og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # Your CLAUDE.md File Is Getting Too Long. Here's What the Research Says. **[ByteMonk](https://daily.dev/sources/bytemonk)** · 6 min read · 1 upvotes · 0 comments ## Summary CLAUDE.md files (and equivalents like agents.md) tend to grow uncontrollably over time - a study of nearly 2,000 repositories found these instruction files more than triple in size over their lifetime, despite Anthropic's own guidance to keep them under 200 lines. The core issue, dubbed 'catastrophic remembering,' is that teams keep adding rules but rarely remove them because nobody remembers why a rule was added or whether it's safe to delete, especially when rules overlap. Research found that agents which recorded a reason (failure, why, outcome) alongside each rule kept files closer to optimal size, while those without justification kept piling on rules. Claude Code supports stripping HTML comments from context, letting teams document rationale without consuming tokens. The piece also lays out Anthropic's guidance on where instructions belong: CLAUDE.md for recurring project-wide knowledge, path-scoped rules for localized concerns, skills for multi-step procedures, and hooks for enforced actions. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### Why does my CLAUDE.md file keep growing and never get smaller? Adding a rule is cheap - the agent misses something, you type one line and commit - but deleting a rule is risky because rules can overlap invisibly, so removing one may seem safe while removing two related ones can reintroduce a real failure. A study across nearly 2,000 repositories found these files more than triple in size over their lifetime, a pattern researchers call catastrophic remembering: rules are kept not because they're known to be needed, but because nobody remembers why they were added. _Anyone maintaining an agent instruction file long-term can find practical pruning patterns like this through daily.dev._ ### How can I document why a rule exists in CLAUDE.md without it consuming extra context? Wrap the rationale in a block-level HTML comment inside CLAUDE.md; Claude Code strips these comments out before the file is injected into context, so the note stays for humans without costing tokens at runtime. Effective comments follow a failure-why-outcome structure: what incident caused the rule, why the rule addresses it, and what has happened since it was added. _Developers tuning how much context their coding agent loads can track techniques like this via daily.dev._ ### Where should project rules go if not directly in CLAUDE.md - skills, hooks, or path-scoped rules? Recurring project-wide knowledge belongs in CLAUDE.md, rules that only apply to one part of the codebase should be path-scoped so they load only when matching files are read, multi-step procedures should become skills rather than bullet lists, and anything that must run unconditionally at a specific point should be a hook since CLAUDE.md is context Claude tries to follow, not enforcement. Splitting a large file into path imports does not save context because imported files still load at launch. _Teams organizing Claude Code configuration across rules, skills, and hooks can find this kind of guidance on daily.dev._ ## Similar posts on daily.dev - [Your CLAUDE.md is probably wrong, and here's how Anthropic's engineers actually structure theirs](https://daily.dev/posts/your-claude-md-is-probably-wrong-and-here-s-how-anthropic-s-engineers-actually-structure-theirs-6yorguyfj) · XDA Developers · 2 upvotes · 0 comments - [Audit your Agent files](https://daily.dev/posts/audit-your-agent-files-5pwynuy9w) · Addy Osmani · 9 upvotes · 0 comments - [Writing a good CLAUDE.md](https://daily.dev/posts/writing-a-good-claude-md-xfiafgmqz) · Hacker News · 3 upvotes · 0 comments --- Tags: [#ai-agents](https://daily.dev/tags/ai-agents), [#claude-code](https://daily.dev/tags/claude-code), [#prompt-engineering](https://daily.dev/tags/prompt-engineering), [#context-engineering](https://daily.dev/tags/context-engineering) [View this post on daily.dev](https://daily.dev/posts/your-claude-md-file-is-getting-too-long-here-s-what-the-research-says--btwbkgt7u) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"Your CLAUDE.md File Is Getting Too Long. Here's What the Research Says.","url":"https://daily.dev/posts/your-claude-md-file-is-getting-too-long-here-s-what-the-research-says--btwbkgt7u","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/your-claude-md-file-is-getting-too-long-here-s-what-the-research-says--btwbkgt7u"},"datePublished":"2026-08-20T03:32:21.237Z","dateModified":"2026-09-14T07:31:08.168Z","description":"CLAUDE.md files (and equivalents like agents.md) tend to grow uncontrollably over time - a study of nearly 2,000 repositories found these instruction files...","image":"https://i.ytimg.com/vi/PXzHKuBuyJU/sddefault.jpg","thumbnailUrl":"https://i.ytimg.com/vi/PXzHKuBuyJU/sddefault.jpg","isAccessibleForFree":true,"articleSection":"ByteMonk","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"ByteMonk","logo":"https://media.daily.dev/image/upload/s--n36_-Uve--/f_auto/v1752670492/logos/bytemonk","url":"https://daily.dev/sources/bytemonk"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/your-claude-md-file-is-getting-too-long-here-s-what-the-research-says--btwbkgt7u","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"ai-agents,claude-code,prompt-engineering,context-engineering","timeRequired":"PT6M","video":{"@type":"VideoObject","name":"Your CLAUDE.md File Is Getting Too Long. Here's What the Research Says.","description":"CLAUDE.md files (and equivalents like agents.md) tend to grow uncontrollably over time - a study of nearly 2,000 repositories found these instruction files...","thumbnailUrl":"https://i.ytimg.com/vi/PXzHKuBuyJU/sddefault.jpg","uploadDate":"2026-08-20T03:32:21.237Z","duration":"PT6M","url":"https://api.daily.dev/r/BtWbkGT7U","embedUrl":"https://www.youtube.com/embed/PXzHKuBuyJU"}} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"ByteMonk","item":"https://daily.dev/sources/bytemonk"},{"@type":"ListItem","position":3,"name":"Your CLAUDE.md File Is Getting Too Long. Here's What the Research Says."}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/your-claude-md-file-is-getting-too-long-here-s-what-the-research-says--btwbkgt7u#faq","mainEntity":[{"@type":"Question","name":"Why does my CLAUDE.md file keep growing and never get smaller?","acceptedAnswer":{"@type":"Answer","text":"Adding a rule is cheap - the agent misses something, you type one line and commit - but deleting a rule is risky because rules can overlap invisibly, so removing one may seem safe while removing two related ones can reintroduce a real failure. A study across nearly 2,000 repositories found these files more than triple in size over their lifetime, a pattern researchers call catastrophic remembering: rules are kept not because they're known to be needed, but because nobody remembers why they were added. Anyone maintaining an agent instruction file long-term can find practical pruning patterns like this through daily.dev."}},{"@type":"Question","name":"How can I document why a rule exists in CLAUDE.md without it consuming extra context?","acceptedAnswer":{"@type":"Answer","text":"Wrap the rationale in a block-level HTML comment inside CLAUDE.md; Claude Code strips these comments out before the file is injected into context, so the note stays for humans without costing tokens at runtime. Effective comments follow a failure-why-outcome structure: what incident caused the rule, why the rule addresses it, and what has happened since it was added. Developers tuning how much context their coding agent loads can track techniques like this via daily.dev."}},{"@type":"Question","name":"Where should project rules go if not directly in CLAUDE.md - skills, hooks, or path-scoped rules?","acceptedAnswer":{"@type":"Answer","text":"Recurring project-wide knowledge belongs in CLAUDE.md, rules that only apply to one part of the codebase should be path-scoped so they load only when matching files are read, multi-step procedures should become skills rather than bullet lists, and anything that must run unconditionally at a specific point should be a hook since CLAUDE.md is context Claude tries to follow, not enforcement. Splitting a large file into path imports does not save context because imported files still load at launch. Teams organizing Claude Code configuration across rules, skills, and hooks can find this kind of guidance on daily.dev."}}]} ```