Comment by sebra
5 hours ago
The tweet misses the conclusion from the paper that handcrafted AGENTS.md might help. To me its no surprise that 100% vibed AGENTS.md are unproductive. Not reviewing your design docs is probably even worse than not reviewing your code? I've seen some AI-generated agents.md which were just plain wrong. No surprise agents perform worse after reading those.
I use AGENTS.md to make sure my agents loop effectively (tests, quality, etc). Not to describe the code / architecture.
> To me its no surprise that 100% vibed AGENTS.md are unproductive.
To me it is! I thought if an AGENTS.md is researched with much effort once, next time reading the brief conclusion would save on effort and time and cost. Would have seemed logical to me. Like a glossary, looking up a manual, getting briefed before starting.
But I accept the research findings, and I have even had bad experiences with an outdated AGENTS.md derailing the agent.
So now I'm trying to keep to the basics, e.g. just a sentence or two saying "use bun instead of npm" only because I've had to manually prompt that too many times.
It's remarkable how good agents are at exploring, and at treating relatively sparse code reads and get a good picture nevertheless.
Don't describe the code / architecture in AGENTS.md - BUT tell the agent where the documentation for both can be found for each module etc.
This way it can refer to the docs only when relevant instead of dragging around the full knowledge of the front-end structure while it's working on the backend.