Updated
Why do AGENTS.md / CLAUDE.md context files stop scaling?
A context file that helps at 5 docs works against you at 50. The agent has finite attention, so a long overview buries the few lines that matter under the ones that don't. A 2026 ETH Zurich study found that adding repository context files tended to reduce task success and raised inference cost by over 20% versus no repo context. Keep the file short and about constraints; serve the changing detail per task, not in one growing file.
The file that helped at 5 docs hurts at 50
A single context file is a fixed prompt prepended to the agent's work. At a small scale that's fine, the whole project fits and the signal is dense. As the project grows, the file grows, and now every task pays to read architecture it doesn't need to answer the question in front of it. Worse, the few relevant lines sit in the middle of a long document, where models attend least (the "lost in the middle" effect). You're paying more tokens for a worse signal.
What the ETH Zurich study found
In Evaluating AGENTS.md (Gloaguen et al., 2026), researchers tested coding agents with and without repository context files on SWE-bench and a fresh issue set. Their finding, in their words: "context files tend to reduce task success rates compared to providing no repository context, while also increasing inference cost by over 20%." The exception was telling: only short, human-written files that state minimal constraints helped. Big, auto-generated overviews hurt. The problem isn't context; it's naive context.
Keep the file short; serve the rest
The fix is two layers, not one bloated file:
- A short context file for the stable, always-true rules, conventions, the review bar, the things every task should respect. Keep it tight and current.
- Retrieval for the rest. Index the changing doc set and serve the one canonical doc that answers a given query, with a freshness marker, instead of prepending everything. The agent gets the right slice for this task, not the whole project every time.
How trovex does it
trovex is an open-source, local-first MCP server that handles the second layer. It indexes your repo's markdown and answers a query with the single current doc (a path:line pointer, marked canonical, stale, or duplicate, down to the section), so the agent reads one right answer instead of sifting candidates or carrying your whole project in its prompt. It runs on your machine (vectors in SQLite, ONNX embeddings, no cloud or API keys) and cuts about 60% of the tokens per lookup. See the measured breakdown in what context costs your agents.
FAQ
Do AGENTS.md / CLAUDE.md files help coding agents?
At a small scale, a short human-written file of stable rules helps. As the doc set grows, a single file works against you: a 2026 ETH Zurich study found that adding repository context files tended to reduce task success and raised inference cost by over 20% versus no repo context. Keep the file short and constraint-focused; serve the changing detail another way.
Should I delete my CLAUDE.md?
No. Keep a short one for stable, project-wide rules an agent should always follow. The failure mode is the big, auto-generated, everything file, not a tight set of constraints. Trim it to what is always true and current.
What replaces a big context file as a project grows?
Retrieval that serves the right slice per task instead of one static file that ages. Index your docs and return the single canonical doc that answers a given query, with a freshness marker, rather than prepending the whole project to every prompt. trovex does this and cuts about 60% of the tokens per lookup.
Is this just RAG?
It is retrieval, but tuned for the agent case: one canonical answer per query with a canonical, stale, or duplicate marker, section-level, not a pile of similar chunks. The point is to hand the agent the current source of truth, not more candidates to sift.
Keep the file short. Serve the rest.
Point trovex at your docs and let your agents pull the one current answer per task.
Open source. No cloud, no API keys. Your docs never leave your machine. Running agents across a team in production? tsukumo (the team behind trovex) helps you operate them.