The Three Golden Rules of CLAUDE.md: Don't Let AI Get Dumber the More It Reads

Many developers habitually stuff their project README verbatim into CLAUDE.md, assuming that more context for the AI is always better. The YouTube channel DevDeck calls out this misconception directly in a short video: dumping hundreds of lines of documentation into a rules file only burns through the context window and actually makes the AI assistant dumber.

The three golden rules presented in the video come from the practice of seasoned engineers. The core logic is simple — CLAUDE.md is not project documentation; it's a set of behavioral constraints for the AI.

Rule One: The Delete Test

The first rule is the "delete test": if removing a given instruction wouldn't cause the AI to make a mistake under a fresh prompt, delete it immediately.

This criterion is razor-sharp. It turns "is this rule useful?" from a subjective feeling into a verifiable experiment. Many rules files balloon because developers write in "just in case" items — worrying that the AI doesn't know some convention, some background, or some historical decision. But the delete test forces you to answer one question: without this, would the AI actually get it wrong? If the answer is no, it's consuming precious context budget.

What's interesting is that this rule carries an implicit premise: the context window is a limited resource. Every extra irrelevant instruction dilutes the attention the model can allocate to genuinely important information. This is the real meaning behind the video's opening line about "making the AI assistant dumber" — it's not that the model's capabilities decline, but that useful information gets buried in noise.

Rule Two: Write Only Precise Commands

The second rule demands "write only precise commands": don't explain what your app does — just list the exact test and build commands, such as pnpm test or pytest.

This rule strikes directly at the question of what CLAUDE.md is for. The AI can infer what the project does by reading the code; but which package manager the repo uses, how to run tests, and what the build script is called can't always be reliably deduced from the code — those are worth spelling out. In other words, the rules file should carry information that the AI "cannot discover on its own from the code but must know."

Replacing long passages of app descriptions with a few lines of commands reduces both token consumption and the risk of the AI misunderstanding the project — outdated feature descriptions are more dangerous than none at all.

Context Window is the key premise for understanding this entire article. It refers to the maximum number of tokens a large language model can receive in a single inference pass, covering system prompts, rules files, conversation history, code snippets, and tool return results. Models like Claude typically have context windows on the order of 200K tokens, which seems generous, but in practice it gets rapidly eaten away by multi-turn conversations and file reads, and there's also the "lost in the middle" phenomenon — content located in the middle of a long context is more easily ignored by the model. Therefore, the more tokens the rules file occupies, the less budget remains for genuinely task-relevant information. "Making the AI dumber" is precisely the result of useful signals being diluted by noise.

Rule Three: Progressive Disclosure

The third rule is "progressive disclosure": rather than dumping an entire database schema in, write a single line pointing to a dedicated document.

This approach mirrors lazy loading in software design. The root rules file keeps only an index; specifics go into separate documents that the AI reads when needed. This controls the size of the root file while preserving accessibility to in-depth information. The video's recommendation is to keep the root rules file under 50 lines.

The number 50 isn't a hard metric per se, but it provides a useful psychological anchor: when you find your rules file approaching or exceeding this size, it's time to run the delete test again.

Progressive Disclosure originates from interaction design and technical documentation writing, with the core idea of "presenting on demand": first give the minimum necessary information and an index, then let the user or system expand details layer by layer as needed. In AI coding assistants, this means the root rules file only contains pointers like "database schema — see docs/schema.md," and the model reads that file when a relevant task arises. A companion mechanism is Agent Skills — packaging domain-specific operational workflows into standalone files that the model can load on demand, matching context usage to actual need rather than injecting everything at once.

Why These Three Rules Deserve Serious Attention

What makes DevDeck's video resonate is that it makes explicit a cost that's easily overlooked in AI engineering: context isn't free. Every instruction competes with code, conversation history, and tool output for the model's attention budget.

The three rules actually form a closed loop: the delete test handles cleanup of existing content, precise commands control information density, and progressive disclosure manages incremental additions. All three point to the same goal — keeping CLAUDE.md lean, actionable, and maintainable.

The question posed at the end of the video is worth every developer asking themselves: how many lines is your rules file right now? If the answer makes you hesitate, perhaps it's time to start with the delete test and do some subtraction on your rules file.

Attention Budget isn't a strict technical term but a plain-language summary of how the Transformer attention mechanism actually performs. The model computes attention weights for every token in the context; irrelevant content spreads out the weight that should be concentrated on key instructions, leading to reduced adherence to critical constraints. Research shows that when a large amount of task-irrelevant instructions is mixed into the context, the model's recall of target instructions drops significantly. This explains why a lean rules file is often more effective than a piled-up one — reducing distractions alone improves the stability of instruction following.

One-line Summary

CLAUDE.md should be lean behavioral constraints, using the delete test, precise commands, and progressive disclosure to control context costs.

Paragraph Summary

The article critiques the common developer practice of dumping project READMEs directly into CLAUDE.md, pointing out that this crowds the context window and dilutes model attention, actually making the AI assistant perform worse. The author cites three golden rules from a DevDeck video: the delete test requires removing instructions that wouldn't cause the AI to err if deleted; precise commands require writing only test and build commands rather than explaining app functionality; progressive disclosure requires using one-line pointers instead of full schema dumps and keeping the root file under 50 lines. The three rules form a loop of cleaning up existing content, controlling density, and managing incremental additions, with the shared goal of keeping the rules file lean, actionable, and maintainable.