Why Overloading CLAUDE.md Makes Your AI Dumber

When using Claude Code, Cursor, or Gemini CLI, developers often fill CLAUDE.md (or AGENTS.md) with dozens of project rules, yet the model frequently ignores them and repeats basic mistakes.

"IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant."

Claude Code injects a system‑level reminder; an overly long CLAUDE.md is treated as “noise” and is more likely to be ignored.

First principle: AI is a stateless “new employee”

Each new session is the AI’s first day; it knows nothing about the codebase. CLAUDE.md becomes its only onboarding manual and long‑term memory, so it must be concise and focused.

HumanLayer summarizes the optimal onboarding content as “The Trinity”:

WHAT (Map): What is the tech stack? What is the project structure (especially in a monorepo, where are the apps and libs)?

WHY (Goal): What is the core value of the project? Where do the responsibilities of core modules lie?

HOW (Tools): How to build? How to run tests? Use npm or bun?

Anything beyond these three elements wastes the AI’s attention.

Best practice 1: Less is More

Research shows that even the most advanced reasoning models reliably follow only about 150‑200 instructions; smaller models (e.g., Haiku or GPT‑4o‑mini) see compliance drop exponentially as instruction count grows. LLMs also suffer from “position bias”: they focus on the system prompt and the latest dialogue, so middle sections of a long CLAUDE.md are often forgotten.

Do not try to cover every edge case.

Keep the root CLAUDE.md under 300 lines ; HumanLayer’s production environment limits it to 60 lines .

Ask for each line: “If this line were removed, could the AI still get the job done?”

Best practice 2: Progressive Disclosure

If many conventions must be documented, split them into a dedicated documentation folder: .ai/docs/testing.md: detailed testing guide. .ai/docs/database.md: schema definitions and migration rules. .ai/docs/architecture.md: core architecture diagrams and data flow.

In CLAUDE.md, retain only “triggers” that point to these files, for example:

"Before writing or running tests, please read .ai/docs/testing.md ." "When making database changes, refer to .ai/docs/database.md ."

This prevents unrelated backend schema information from polluting the context when the AI is generating front‑end code.

Best practice 3: Don’t Use AI as a Linter

Embedding dozens of style rules (e.g., “use 2‑space indentation”, “no line break after braces”, “camelCase variable names”) in CLAUDE.md wastes the model’s inference budget; LLMs are probabilistic generators and can still slip.

Combine deterministic tooling with AI feedback:

Configure tools such as Prettier, Biome, ESLint, or govet to enforce formatting.

Set up Claude Code’s Stop Hook so that when the AI produces code with a lint error, the error message is fed back to the model.

AI: (generates code) System: "Lint Error: Missing semicolon." AI: "Ah, fixing it."

AI excels at fixing reported errors but is not suited to silently follow invisible style rules.

Conclusion: Lever hierarchy

In AI‑native development, CLAUDE.md sits at the top of the “lever hierarchy”. A single erroneous line can cascade into hundreds of planning, retrieval, and code errors. Keep the file concise, split extensive documentation, and let deterministic tools handle formatting. Reducing the AI’s “baggage” lets it operate faster and more reliably.

Full analysis: https://www.humanlayer.dev/blog/writing-a-good-claude-md