If you are using Cursor or Claude Code in your projects, there is a good chance your CLAUDE.md file is actively working against you. That is the finding from developer blncraft on DEV.to, who reviewed dozens of codebases and kept encountering the same four mistakes that were burning token budgets and causing AI assistants to ignore important project rules.

Mistake #1: The 3,000-Token Monster

Most CLAUDE.md files developers create balloon to over 3,000 tokens of aspirational guidelines. Every single response, the AI reads this entire file before answering—eating up context window and often getting ignored anyway. The fix is straightforward: keep your main CLAUDE.md under 800 tokens and offload framework-specific details into separate files using @include directives. This way, only relevant includes load for each specific file you are working on.

Mistake #2: Rules Without Globs Never Fire

Generic rules like "always write tests" do nothing if your AI does not know when to apply them. Cursor and Claude Code support glob-scoped rule files—.mdc files with frontmatter that specifies which file patterns should trigger the rule. A testing rule scoped to **/*.test.ts only fires when you are editing test files, keeping everything else clean and focused.

Mistakes #3 & #4: One-File-Catches-Nothing

A monolith CLAUDE.md covering every concern ends up covering nothing effectively. The same rules get applied whether you are writing Go services or React components—context that does not apply creates noise. Additionally, long multi-concern rule files get treated as background noise entirely. The AI picks what it thinks matters and skips the rest.

Recommended Project Structure

The solution is modular organization by domain: separate directories for auth rules (14 files), database patterns (18 files), testing conventions (22 files), UI components (31 files), deployment configs (15 files), and observability logging (12 files). Each contains focused, single-concern rules that auto-attach via glob patterns. The main CLAUDE.md stays under 800 tokens as a team conventions primer.

Measurable Results

After implementing this structure, developers reported token usage per session dropping by approximately 40 percent. Rules actually fired at the right time because they were finally scoped correctly. New team members could understand the AI setup in under ten minutes instead of wading through walls of generic guidelines.

Bottom Line

Your CLAUDE.md should be an introduction, not an encyclopedia. Smaller files that auto-attach by pattern outperform long catch-all documents every single time—and your token budget will thank you for it.