Why Overly Long Context Files Reduce AI Agent Success by 3% and Raise Token Cost 20%

Recent research from ETH Zurich (arXiv:2602.11988) demonstrates a clear inverse relationship between an AI agent’s efficiency and the length of its context files. Providing a fully‑filled context file does not improve performance; instead, it reduces task success rate by roughly 3 % and increases token consumption by about 20 %.

The root cause is the model’s fixed instruction budget, which tops out at approximately 150‑200 discrete instructions per session. System prompts already consume around 50 slots, leaving limited capacity for user‑supplied context. Longer files dilute attention, cause the agent to over‑obey irrelevant or outdated information, and ultimately push useful instructions out of the budget.

To mitigate this, the article proposes a "Key Few" principle: only encode information that the agent cannot infer from the code base. This includes a concise project description, exact technology‑stack versions, precise CLI commands (e.g., npm test -- --runInBand or pytest tests/ -x -v), and a handful of hard constraints such as "never log confidential data" or "never call the payment API from the frontend". The root context file should be limited to 60‑80 lines.

Two complementary files are recommended: CLAUDE.md , which contains the agent‑specific, narrow instructions, and AGENTS.md , a tool‑agnostic source of truth similar to a .gitignore. The latter can be imported into CLAUDE.md with @import AGENTS.md, ensuring cross‑tool compatibility without duplicate maintenance.

Context hierarchy is also important. Three levels remain active simultaneously: a global file (~/.claude/CLAUDE.md) for personal preferences (kept under 15 lines), a project‑level ./CLAUDE.md stored in version control, and a local ./CLAUDE.local.md (git‑ignored) for machine‑specific settings such as URLs or environment variables. Secrets must never appear in any context file; they belong in a .env file.

When the agent’s knowledge becomes stale—e.g., a file path was renamed months ago—the fix is to update CLAUDE.md with a direct instruction like "Update CLAUDE.md to stop using the old path". Over time, this iterative refinement shortens the root file while preserving essential directives.

Additional tooling can automate verification. The built‑in /init command suggests improvements without overwriting existing files, while the open‑source tool Agnix validates CLAUDE.md and AGENTS.md against 385 rules derived from official specifications and real‑world failure modes. Anthropic’s official plugin performs a five‑stage audit, presenting diffs and rationales before applying changes.

Finally, the article emphasizes progressive disclosure: keep the root CLAUDE.md under 60‑80 lines, reference deeper documentation (e.g., "see docs/db-conventions.md"), and use a separate MEMORY.md file (up to 200 lines) for the agent’s self‑generated knowledge. This layered approach balances brevity, clarity, and the ability to navigate complex codebases efficiently.