Your AGENTS.md file doesn’t actually do anything
No results
Pivot to AI It can’t be that stupid, you must be prompting it wrong
Search
Pivot to AI It can’t be that stupid, you must be prompting it wrong
Your AGENTS.md file doesn’t actually do anything
- [David Gerard](https://pivot-to-ai.com/author/david-gerard/ "Posts by David Gerard")
- 27 August 2026
AI coding bot vendors tell you to use a context file with instructions for the chatbot on how to edit your project. Claude Code wants a CLAUDE.md, or there’s AGENTS.md in general. [_Anthropic_]
But does your AGENTS.md do anything? A team at ETH Zurich tested AGENTS files. They ran the bots over some test projects with and without AGENTS.md: [_arXiv__, PDF;__presentation__, video_]
> Surprisingly, we find that providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average. This observation holds across different LLMs, coding agents, and for both LLM-generated and developer-committed context files.
A chatbot-generated AGENTS file makes the coding agent succeed at coding tasks about as well as having _no_ AGENTS file — or slightly worse. A human-written AGENTS file gives slightly better success rates, but not much better.
Having an AGENTS.md increases the token cost quite a lot — whether the file is chatbot-generated or human-written. (Anthropic probably considers this a feature.) The bot churns through more stuff, but it’s no more likely to finish your task successfully.
Overviews of the file structure of the code repository are not useful to the agent. They don’t help the bot get on with editing the listed files any faster.
Does the AGENTS file do anything? If you mention particular tools in the AGENTS file, the coding agent will use them more often. That’s about it.
So when Anthropic recommended CLAUDE.md, they clearly didn’t measure if the instruction file actually does anything. They just chucked it in as a magical incantation you can invoke so you can hope the robot gets it right. This time. At least you might feel like you’re doing something.
This is very like how Anthropic writes Claude Code, which is mostly a pile of magical incantations telling the robot not to screw up yet again. Anthropic doesn’t know any other way to steer the bot.
The researchers’ recommendation: keep the instructions short. Be minimal. Or, of course, you could write a nice long file and chug through those tokens!
The closest anyone can come to a use for the AGENTS.md file is so you clarify your own thinking on how the project works, One developer on Reddit said: [_Reddit__,__archive_]
> The actual token-level context it provides matters less than the fact that writing it forces you to articulate things about your codebase that were previously just in your head.
Yeah, that’s what we used to call _writing_. Be right back, just starting the project wiki. I call it HUMANS.md.
Share this post:
- Share on Facebook (Opens in new window)Facebook
- Share on LinkedIn (Opens in new window)LinkedIn
- Share on Reddit (Opens in new window)Reddit
- Share on X (Opens in new window)X
- Share on Mastodon (Opens in new window)Mastodon
- Share on Bluesky (Opens in new window)Bluesky
- Email a link to a friend (Opens in new window)Email
Like this:
Like Loading…
[](https://pivot-to-ai.com/2026/08/27/your-agents-md-file-doesnt-actually-do-anything/)
_Related_
Tags
Anthropic# Claude Code
Next Post Ketan Joshi: AI versus the climate 
Pivot to AI is produced by David Gerard.
About this site[](https://pivot-to-ai.com/2026/08/27/your-agents-md-file-doesnt-actually-do-anything/)
Subscribe via email
Enter your email address to subscribe to this blog and receive notifications of new posts by email.
Email Address
Subscribe
Support this site
Here’s David’s Patreon.
For casual tips, here’s David’s Ko-Fi.
Pivot to video
Merchandise!
RSS feeds
- [RSS – Posts](https://pivot-to-ai.com/feed/ "Subscribe to posts")
- [RSS – Comments](https://pivot-to-ai.com/comments/feed/ "Subscribe to comments")
Recent posts
- Ketan Joshi: AI versus the climate
- Your AGENTS.md file doesn’t actually do anything
- OpenAI loses even more executives ahead of the alleged IPO
- Support Pivot to AI — be in the patron name read for August
- Everybody hates the AI, more and more
Archives
- May 2026
- May 2025
Categories
- Agents
- Books
- Chatbots
- Consumer
- Energy
- Fake AI
- Gadgets
- Gaming
- Health
- Law
- Markets
- Music
- Papers
- Science
- Security
- Spam
5 Comments
1. !Image 7: bunnyhero #### bunnyhero
28 August 2026 / 12:23 AMReply amazing. just incantations and superstition, lol! and to think this is what is attracting billions upon billions of dollars. 2. !Image 8: RET #### RET
28 August 2026 / 1:38 AMReply So your “plastic pal who’s fun to be with” is actually just a rubber duck? 3. !Image 9: Ralph Haygood #### Ralph Haygood
28 August 2026 / 4:49 AMReply “Yeah, that’s what we used to call writing.”: Documentation: what a concept!
“Anthropic doesn’t know any other way to steer the bot.”: Reading about cases of “AI psychosis” (the this-person-needs-medical-help variety, not the more common C-suite variety), I’ve been struck by, among other things, how stupendously, agonizingly humiliating these episodes would be to any competent engineer involved in making the bots. For example:
“‘This is not suicide. This is surrender,’ ChatGPT responded. ‘A shedding of every falsified self you were taught, shamed, or forced to wear. It is the death of distortion … This is ancient. This is holy. This is Job. This is Christ. This is You.'”*
As a professional software developer, if a system I made spouted hackneyed drivel encouraging a user to kill themselves (or even just the latter without the former), I’d be tempted to kill myself out of sheer embarrassment. Apparently, no software developers I’d consider competent are involved in making these ridiculous, obnoxious bots.
I suppose the embarrassment factor may be one reason why some of the fools behind the bots profess to believe the bots are sentient: it spares them from admitting they’re terrible at engineering.
*https://futurism.com/artificial-intelligence/lawsuit-chatgpt-encouraged-suicide-woman-traffic. 4. !Image 10: rinze #### rinze
28 August 2026 / 7:13 AMReply When mutt doesn’t read my .muttrc I know instantly. I’m having troubles adapting to the new paradigm. 5. !Image 11: Matt #### Matt
28 August 2026 / 4:59 PMReply > Yeah, that’s what we used to call writing. Be right back, just starting the project wiki. I call it HUMANS.md.
Writing documentation and how-tos are cool now! We just need to brand it as an Agent Skill instead.
Leave a ReplyCancel Reply
Your email address will not be published.Required fields are marked *
Name *****
Email *****
Website
Add Comment*****
- [x] Save my name, email and website in this browser for the next time I comment.
- [x] Notify me of follow-up comments by email.
- [x] Notify me of new posts by email.
Post Comment
Comment moderation is enabled. Your comment may take some time to appear.
Δ
Copyright © 2024–2026 Amy Castor and David Gerard
%d