After spending more time trying to optimize the heck out of my AGENTS.md file, and reading more feedback from other people trying to do the same, I've come to the conclusion that for many people, it's hurting more than helping.
For a while there I thought it was just me, struggling to get my agent to actually read and follow what I put in AGENTS.md, but after seeing this tweet from Karpathy I realized, okay - it's not just me.
Karpathy says it directly: "The agents do not listen to my instructions in the AGENTS.md files."
I think the core of the issue here is that Agents don't need more text, what they really need is better state. This is something Anthropic talked about back in September of last year...but I missed it. I don't like including links in my articles because then ppl accuse me of being a shill, so you can go find the article if you want, it's called "Effective context engineering for AI agents" and it's from Sept 29th of last year.
At the core, when you look at an AGENTS.md file, I don't think the issue is whether you have it or not, it's really about if the agents is able to actually get the right commands, constraints, and recent decisions, at the right time. In the article I referenced above from Anthropic, they talk about summarization and compression of critical details as part of how long-running coding agents maintain continuity.
The problem is, and I'm guilty of this as much as anyone else, big AGENTS.md files don't end up making your agents smarter, they really just end up being a tax on every task. OpenAI has talked about this themselves w/respect to Codex, essentially saying that since Codex reads AGENTS.md before starting work, a bloated file can end up being fixed overhead on every run.
Where I'm at now is probably in the extreme "less is more" camp. I think the most useful stuff I'm putting in my AGENTS.md file these days is exact test commands, wacky project-specific setup steps, deployment funkiness, etc. Pretty much things that I don't think the agent is going to get just from reading the code and the README.md file.
The things that I used to put in my AGENTS.md file that I'm leaving out now are things like coding philosophy, which I think was the first thing I pulled out. I see soooooo many sample AGENTS.md files that have these super long-winded coding philosophy blocks in them, get those out - it's such a waste.
I'm also removing things like architecture summaries, stuff that's already in the README.md file, and anything else I think the agent can probably get itself from the codebase.
So while I haven't gotten rid of AGENTS.md completely, and wouldn't tell anyone to completely scrap the file necessarily, I am now, more than anything, treating it as a living exception file.
And yes, I wake up on Monday morning, thinking about these things randomly, which is why I thought I'd whip up this article.
Okay, that's all I got, time for my second cup of coffee, thanks for reading and as my Uncle Irv used to say - TGIM (thank goodness it's Monday).