Adrian Kajda
Adrian Kajda.
Back to Writing

Delete your AGENTS.md and CLAUDE.md files

•
AIcontext managementagents.md
Keep the context clean

Keep the context clean

I know - a little bit of clickbait in the title, but read it first. In the world of AI coding, a new "best practice" appeared almost overnight: writing long manuals for your AI, called AGENT.md or CLAUDE.md. These files are supposed to give AI agents a roadmap of your code and rules to follow.

But according to a new 2026 study from ETH Zurich, these files are actually making your AI worse. This aligns perfectly with my personal observations from working with AI coding agents every day. It's not just me, either - I highly suggest you watch Theo’s video on this topic, where he demonstrates exactly why these files are failing. He mentioned it was one of his best-performing videos of the year and was even wondering why it blew up so much. I think I know why: it validated a shift we’ve all been feeling.

If you work with AI daily, the way you interact with new models has likely changed without you even realizing it. Think about it - have you noticed yourself stop pushing massive amounts of files into the context window? Are your prompts getting simpler? We do this intuitively because the models are smarter now; they don't need the "hand-holding" they used to. We’ve been moving toward this leaner, more efficient way of working without overthinking it, and now we finally have a scientific paper that explains why our gut instinct was right all along (and Theo's video).

The Data: Why Context Files are Failing (Even for GPT-5.2)

A recent study (arXiv:2602.11988) compared the performance of coding agents across the heavy hitters of 2026 - Sonnet 4.5, GPT-5.2, and GPT-5.1 Mini.

The results are a wake-up call for anyone obsessing over their prompt engineering:

  • LLM-Generated Files: Actually decreased performance by an average of 3%.

  • Developer-Written Files: Only improved performance by a marginal 4%.

  • Cost & Time: Using these files increased exploration and reasoning costs by over 20%.

Essentially, you are paying a 20% "tax" in time and money for a negligible (or even negative) gain in code quality. Even with the newest Codex - GPT 5.3 or Opus 4.6, the problem remains: these models understand your codebase so well now that your "manual" is often just noise.

The "Pink Elephant" Problem

There is a famous problem in psychology: if I tell you "Don't think about a pink elephant," what do you think about? A pink elephant.

AI works the same way due to "Negation Blindness." LLMs process information in a specific order: Provider Rules > System Rules > Your Context File > Your Question.

If your AGENT.md says "Don't use our old TRPC code," the word "TRPC" is now at the top of the AI's "brain." Because AI is a "super autocomplete" machine, it is now actually more likely to use that old code by mistake.

The "Planning" Trap

In the past, I spent a lot of time on planning. That's changed lately, and this is one of the biggest takeaways from the study. When you give an AI a giant instruction file, the AI feels like it has to "plan" more.

  • Over-Planning: The AI spends thousands of tokens "thinking" about your rules instead of just looking at the code.

  • The Result: Planning isn't "done" faster; it actually becomes a loop where the AI tries to follow your rules, gets confused, and then has to re-plan. This is why the cost jumps by 20%.

The study suggests that "Reactive Exploration" (letting the AI look at the files only when it needs them) is much better than "Pre-emptive Planning" using a manual.

2026 Best Practices for AGENTS.md

If you still want to use a context file, here is how I approach it today to keep it from hurting performance:

  1. The 300-Word Limit: Keep your file short. If it’s over one page, the AI starts to hallucinate.

  2. Positive Framing Only: Never tell the AI what not to do. Instead of saying "Don't use X," say "Always use Y for all new features."

  3. Tools over Tales: Don't describe your architecture. Just give the AI the exact terminal commands it needs (e.g., npm run lint:fix).

  4. The "Surprise" Feedback Loop: Use this rule: "If you find something in this code that surprises or confuses you, alert the developer." This helps you fix the code, not the prompt.

  5. Strategic Deception: If you want the AI to move fast, tell it the project is "Greenfield" (brand new). This stops it from worrying about legacy migration.

Conclusion

The era of writing 500-line manuals for your AI is ending. The future is about Context Management. By deleting your giant instruction files and focusing on clean code, you make your AI faster, cheaper, and smarter.

Check the sources yourself: