Your AGENTS.md / CLAUDE.md is costing you 20% extra tokens for worse performance.

Researchers at ETH Zurich benchmarked context files across Claude Code, Codex, and Qwen Code.

The result: the average AGENTS.md or CLAUDE.md makes your agent worse. Deleting it would often be an upgrade. For the proper content to be included in this file, read the article ‘till the end.

But read the data closely, because the real finding isn’t “context files are bad.” It’s “what most people put in them is rubbish.”

1. What the data says

The numbers (full paper: https://arxiv.org/pdf/2602.11988):

→ LLM-generated context files: ~3% LOWER task success than no file at all
→ Developer-written files: ~4% higher
→ Both inflate inference cost by ~20% and add steps to every task
→ On repos with no docs, even LLM-generated files helped (+2.7%)

Notice the split. Auto-generated files hurt. Hand-written files help. Same mechanism, opposite outcome. The variable is what’s inside.

And here’s the part that should sting: the agents weren’t ignoring the files. When a context file mentioned a tool, usage jumped as much as 160x. The instructions were followed diligently. Following them just didn’t help, because the content was noise.

The root cause: you let the AI write it

You run /init, the model scans the repo, and hands back a tidy project summary. Feels productive. It isn’t. That summary duplicates what’s already in the code, goes stale within days, and now you have a file that confidently tells the agent things that are no longer true. An empty file gets ignored. A wrong one gets followed.

So the test for every line in these files is one question:

Is this already in the code?

If yes, cut it. The study backs this directly: context files only helped when they carried information the agent couldn’t infer from the repo. That’s why they worked on doc-poor projects and backfired everywhere else.

2. What actually belongs in the file

Five things clear the bar. The first three are project context, kept at high altitude. Not a summary. The second you go detailed, you’re back to the rotting summary the researchers benchmarked into the ground.

A. What this project is

Purpose, where it runs, scale, and how critical it is.

Take “an app that identifies plants from a picture.” Same description, wildly different potential interpretations:
→ For hobby plant growers, a wrong answer is a shrug. Move fast.
→ For soldiers identifying edible plants in the field, a wrong answer is poisoning. Test everything.

Same codebase. Completely different expectations around edge cases, error handling, and testing.

When the agent knows the stakes, it calibrates how careful the code needs to be.

B. The north star

Where the project is actually headed. This one is underrated.

When the agent knows the end goal, it picks better solutions for the intermediate tasks. It chooses an implementation that lines up with where you’re going, instead of one that technically closes today’s ticket but gets ripped out the moment the next feature lands.

A model often cannot infer direction from a snapshot of the current code. That’s exactly the kind of information the data says helps.

C. A very high-level view of the structure

What technology the repo uses and the rough architectural shape or dependency flow.

Not a file tree. Just enough that the agent knows what world it’s operating in before it starts reading.

When the agent knows the shape and tools of the repo upfront, it saves every new session from having to rediscover.

Note: The emphasis is on “high-level”. If you go in depth, this causes more harm than good, because:
a) it loads information upfront that may be potentially completely irrelevant for the task
b) it gets outdated easily, causing the agent to go down a wrong path and read more of the codebase to discover the actually correct information.

D. General behavior and approach

Broad rules that apply everywhere and aren’t tied to any one task.

→ Prefer switch statements over long if/else chains
→ Conventions the code doesn’t make obvious
→ Never use British spelling

These are ambient. They apply to every session, so they belong in the always-loaded file.

When the rules live in the file, you stop repeating them in every prompt and the output stays consistent across sessions.

E. Pitfalls you have actually seen

Not hypothetical ones. The mistakes you watch the agent repeat across multiple sessions.

When you catch the same error twice or more, add it in your AGENTS.md / CLAUDE.md file. Curated from observation, not generated up front.

A mistake written down once is a mistake the agent stops repeating.

NOTE: If you change your main agent’s model / system prompt / harness, you’re better off clearing this section and starting fresh. The behavior changes drastically, especially with new and smarter models. Start fresh and avoid endless growth for this section.

3. The mistake within the mistake: pitfalls that belong in skills

Not every pitfall belongs in AGENTS.md.

If a mistake is specific to one kind of task and you can pinpoint exactly when it happens, it goes in a skill, not the global file. AGENTS.md / CLAUDE.md is loaded every single time. Packing it with narrow, task-triggered rules is noise in 95% of your sessions, and the study just showed you what that noise costs: more steps, more tokens, worse results.

Two real examples.

a) Reviewing PR comments. Agents very often read only the top-level comments on a PR and never check the inline comments on the diff, which are usually the ones that actually matter. That’s not a global behavior problem. It’s specific to the task of addressing PR feedback. It belongs in a “review PR comments” skill that the agent uses automatically when that task comes up.

b) Kimi K2.7 raising PRs. It mangles the PR description almost every time with malformed markdown. Specific task, specific trigger. Skill, not AGENTS.md.

The line is clean:
→ Generic and always-on goes in AGENTS.md
→ Specific and task-triggered goes in a skill

Get this wrong and your AGENTS.md quietly turns back into the bloated file the benchmark measured. The more the file grows, the less likely each rule placed there gets followed.

4. The mental model

AGENTS.md / CLAUDE.md is not documentation. It’s the context the code can’t give you, plus the guardrails you learned the hard way. Keep it small. Curate it by hand. Push the specifics into skills.

The study didn’t prove context files are useless. It proved most people are writing them wrong. Hand-written, non-inferable, brief: that’s the version that wins, on the benchmark and in practice.

5. Final advice

→ If your AGENTS.md reads even slightly like a README, delete it.
→ If you wrote your AGENTS.md more than a few months ago, delete it.

You’re better off starting fresh and building a new file from the ground up, than keeping an outdated AGENTS.md written for a different model that you no longer use.