Skip to main content

CLAUDE.md overload: the more rules you write, the fewer get followed

PhaseImplementationRolesEngineer · ArchitectSeverityMediumApplies toAll coding agentsEvidenceOfficial docs

In one sentence: you pour every convention you can think of into CLAUDE.md, hoping I'll cover all of it. Instead, the sheer number of rules makes me lose the important ones—and I drop half of them.

Symptom​

CLAUDE.md is the project handbook I read every time. I often see it grow longer and longer: code style, directory conventions, naming rules, commit format, dozens of "always" and "never" clauses. The intent is good, but once it hits several hundred lines, you'll notice I start ignoring parts of it—and not necessarily the parts you'd consider least important.

Why this happens​

There's a limit to how many instructions I can reliably follow. Empirically, today's frontier models can reliably track on the order of 150–200 instructions, and Claude Code's own system prompt already consumes a chunk of that budget. Every extra rule in CLAUDE.md competes with the others for that finite "attention budget."

More importantly: when rules carry no priority markers, I can't tell which is a hard line and which is a mere preference. The more you write, the more easily the genuinely important constraints get averaged down alongside the trivial ones. This is the same class of problem as the kitchen-sink session—signal-to-noise—except this time the noise comes from the configuration file itself.

Consequences​

  • Key constraints get dropped, while you assume they're "already in the spec."
  • The longer the file, the larger the fixed overhead on every session, and the smaller the window left for the actual task.
  • It's hard to tell which rules are doing anything and which are dead letters.

What to do instead​

Let CLAUDE.md start small and grow on demand. Concretely:

  1. Begin with only the genuinely necessary few (build/test commands, the most core style conventions).
  2. Each time I make a particular mistake, add one rule that addresses it—so every rule has a reason to exist, rather than being pre-imagined.
  3. Review periodically: delete entries that were written but never actually violated.
  4. Don't sprinkle @file references throughout CLAUDE.md—each reference loads the entire referenced file into context, a common source of bloat.

The test is simple: if you can't say "this rule is here to prevent which specific mistake," it probably shouldn't be here.

Example​

Before (excerpt, 200+ lines):

- Name variables in camelCase
- Don't use var
- Comments must be complete sentences
- Functions no longer than 50 lines
- Prefer const
- Every file needs a copyright header at the top
- … (190 more lines)

After (10 lines, each tied to a real lesson):

# Build & test
- After changing code, run `npm test`; ship only when green.

# Traps this project has hit
- Database migrations must be reversible (a missing rollback caused a prod incident).
- Store all times in UTC (mixing time zones caused a bug).

Tool differences​

Gemini CLI (as of 2026-06): Gemini CLI dials this pitfall up a notch: its context is concatenated hierarchically in full into every prompt — the global ~/.gemini/GEMINI.md + the project-root ./GEMINI.md + the src/GEMINI.md for whatever subdirectory you're in, all stuffed together, which overloads more easily than flat loading. Two countermeasures: run /memory show to see the concatenated result I actually receive (not the one you imagine), and push local rules down into the matching subdirectory's GEMINI.md so they only apply under the relevant path, keeping the total footprint down.

Codex CLI (as of 2026-06): Codex's equivalent file is AGENTS.md, merged from the cwd all the way up to the project root (plus ~/.codex/AGENTS.md), and it bloats hierarchically just the same. But it has a hard ceiling: project_doc_max_bytes defaults to 32 KiB, and anything past that is truncated outright — here "keep it short" is enforced by the tool, not just advice.

Cursor (as of 2026-06): Cursor's .mdc rules carry an activation mode, which turns footprint from always-on into conditional: Always (alwaysApply: true, loaded every time — the overload trap), Auto Attached (loaded only when a file matches globs:), Agent Requested (only the description is given, and the model pulls it on demand), and Manual (@rule-name). So trimming the load isn't simply "write less" — it's demoting always rules into a glob scope or agent-requested. The docs note it too: every token of an always rule is consumed in every single request.

GitHub Copilot (as of 2026-06): The same dilution, plus two hard ceilings. GitHub states plainly that an overly long instruction file gets some of its instructions ignored, and Copilot code review reads only the first 4000 characters of the custom-instructions file — anything past that fails silently, where I never even see it. The direction is the same: write short and specific instead of piling on.

Version notes​

Applies to

"A finite number of reliably-followed instructions" is a trait shared by all of today's frontier large language models—all models and coding agents apply. As models improve, this ceiling rises, but "concise, prioritized, every-rule-has-a-reason" will always be more reliable than "big and exhaustive."

Further reading and sources​