A recent study confirms what I've suspected: giving your AI coding agent too many instructions in repository-level context files actually reduces task success.
A recent study proved that providing exhaustive, repository-level context files like AGENTS.md actually reduces AI task success rates and increases API costs by over 20%. To improve your coding agent's performance, human-written instructions should be reduced to only the most vital architectural guardrails, avoiding "Lost in the Middle" context poisoning.
I've been stuffing .cursorrules, claude.md, and AGENTS.md files into repos for months, convinced that more instructions meant better agents. A recent study on arXiv — "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" — says I had it backwards.
Researchers compared coding agents on real-world tasks with LLM-generated context files, developer-written context files, and no repo context at all. Context files tended to hurt success rates across multiple agents and models. They also bumped inference costs by more than 20%.
That tracks with "Lost in the Middle" (Liu et al., 2023): the more you cram into the prompt window, the more the model ignores stuff in the middle and latches onto the edges.
The trace analysis is the interesting part. With an AGENTS.md in play, agents ran more tests and wandered the codebase longer. They were being good interns — following every rule in the file, burning thinking tokens, chasing rabbit holes that had nothing to do with the actual task.
This matches what I've been arguing in context poisoning and the folly of MCP. More input is not better input. A crowded context window degrades reasoning. Agents take instructions literally; tell them to run full code quality checks or unrelated test suites and they'll do it, even when you're asking for a one-line fix. The paper's per-repo breakdown found no repository where context files had a meaningful positive impact.
You wouldn't give a new hire a 100-page logging-style guide before asking them to fix a typo on the marketing page. You'd tell them what's broken and where to look.
Same rule for agents. Context files should cover the minimum: stack, architecture boundaries, where to find known gotchas. That's also why I separate understanding from execution and clear context between plan and build.
Overload the foundational instructions with every edge case and preference, and you dilute the signal. The agent spends its limited attention satisfying constraints that have nothing to do with the job.
Here's a context file that's too long:
# BAD: The Exhaustive Rulebook
- Always use our custom LoggerInterface for every error, never use console.log or standard print statements.
- Every new function must include at least three standalone unit tests using Jest.
- Never use relative imports, always use absolute paths configured in tsconfig.
- Always check the database schema before making any API changes.
- Commits must follow the exact Conventional Commits format with Jira ticket numbers.
- Ensure all new UI components are responsive across mobile, tablet, and desktop breakpoints.
Ask an agent to fix a text alignment bug with that file loaded, and watch it hunt for database schemas and spin up Jest tests nobody asked for.
Here's what I actually want:
# GOOD: The Targeted Guardrails
- We use Tailwind CSS for all styling.
- The project is a Next.js App Router application.
- Check the local `mistakes.md` file before starting a new feature to review previous known issues.
Framework, routing paradigm, a pointer to past mistakes. That's usually enough.
Next time you set up a repo for an agent, resist the urge to document every rule you've ever cared about. Write the guardrails. Delete the rest. Your agent will stop trying to impress you with unnecessary test runs and start fixing the thing you actually asked for.