yes, they do. I think people overindex on this paper, I remember when it came out we had a lot of discussion in my company about it. But its clear to see they do at least change the agent's behavior, and things like telling it "always use xyz version of java, use gradle to build the project, use this command to run the tests" are really important instead of letting it fumble about trying to find the right thing every time you ask it anything
I think the problem some people fall into, and especially LLM authored ones (which is where they see the documents not helping here) is instead describing the code, or the structure of the code. Which I don't think helps much - the agent can already see you have 4 modules called a b c and d, and can read the readmes inside of them just fine if it has questions.
One more marginal thing I find helpful but im less sure has positive impact is describing the right terminology for the agent so it can be smarter at communicating with the developer. Things like different names for the product, products it interfaces with, resource names in infra, terms from the customer and product team. I don't think it helps the agent code (much) but it does help communication if it knows what we mean when we speak (and naming things is, as we know, one of the hard problems in CS)
Overall, most of my agents.md now are a list of useful bash commands for working and testing with the project & tests. (heres how to spin up docker services, heres how to update the libraries, heres how to run a command against the local db, heres how to insert a document to be run etc)
and then at the end a terminology blob, which I find myself referencing too.
Paper was discussed here 4 months ago, and the linked tweet on this post doesn't add any insights and completely misses the huge caveats that come with the found result: the main benefits of using AGENTS.md files are inherently opposed to the characteristics of _median_ "public github project that has an AGENTS.md file".
Yeah it was a good discussion. I'm definitely on the side of "a well written agents.md is very good for the agent". The file should not be static. The agents.md from a year ago is not the right agents.md for today. Many of them are overly long, overly instructive, and include a lot of unccessary code bits.
I think it's useful for people using agent harness to regularly evaluate your skills, agent rules, and memory implementation to ensure there's no conflict across them all. Also, best to rely as little as possible on the agent to write its own agents.md.
It can be be tedious, but that's why agentic coding can still be considered a "skill".
The amount of cargo-culting around AI tooling and practices is so weird to me.
Why not just try and see? The fast feedback loop allow testing all kind of weird theories in a matter of 30m-1h during normal working sessions, most results are obvious
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.
Not enough on its own you'd need artifacts to store contexts/TOC/lists
I think shorter the better.
also a strange finding from my own experiences: specific empirical formats seem to yield much better results. For example people often say "get this done to 100%" but I say "get this to 88.47%".
If adding something to the context doesn't help, it's only proves you're not adding the right stuff.
I'm adding pointers to specification documents, and it saves me from the /new dumb coding agent that sees your code base for the first time and knows nothing about architecture, concepts, code organisation, etc...
I'm using no cookie cutter directives though (except maybe "do not attempt to deploy, we're using CI CD to deploy" to avoid an automatic "wrangler deploy" to Cloudflare)
As the author notes in the end, it would be really interesting to do these again on more recent models. I wonder if the no context file being cheaper still stands. But then how much does the harness influence the results. It can be frustrating trying to gauge what’s influencing what and if something suddenly starts working against you.
The paper actually says:
"We find that all context files consistently increase the number of steps required to complete tasks. LLM-generated context files have a marginal negative effect on task success rates, while developer-written ones provide a marginal performance gain."
"Overall, our results suggest that context files have only marginal effect on agent behavior, and are likely only desirable when manually written."
On a second thought... The result is counter-intuitive, because writing AGENTS.md (and reading if it's generated) contributes to the context in the human. So yes, AGENTS.md probably help more than the paper says, but not the way we initially frame it.
Dunno if there's a way to test that AGENTS.md help the human more than the machine.
yes, they do. I think people overindex on this paper, I remember when it came out we had a lot of discussion in my company about it. But its clear to see they do at least change the agent's behavior, and things like telling it "always use xyz version of java, use gradle to build the project, use this command to run the tests" are really important instead of letting it fumble about trying to find the right thing every time you ask it anything
I think the problem some people fall into, and especially LLM authored ones (which is where they see the documents not helping here) is instead describing the code, or the structure of the code. Which I don't think helps much - the agent can already see you have 4 modules called a b c and d, and can read the readmes inside of them just fine if it has questions.
One more marginal thing I find helpful but im less sure has positive impact is describing the right terminology for the agent so it can be smarter at communicating with the developer. Things like different names for the product, products it interfaces with, resource names in infra, terms from the customer and product team. I don't think it helps the agent code (much) but it does help communication if it knows what we mean when we speak (and naming things is, as we know, one of the hard problems in CS)
Overall, most of my agents.md now are a list of useful bash commands for working and testing with the project & tests. (heres how to spin up docker services, heres how to update the libraries, heres how to run a command against the local db, heres how to insert a document to be run etc)
and then at the end a terminology blob, which I find myself referencing too.
[dupe] https://news.ycombinator.com/item?id=47034087
Paper was discussed here 4 months ago, and the linked tweet on this post doesn't add any insights and completely misses the huge caveats that come with the found result: the main benefits of using AGENTS.md files are inherently opposed to the characteristics of _median_ "public github project that has an AGENTS.md file".
Yeah it was a good discussion. I'm definitely on the side of "a well written agents.md is very good for the agent". The file should not be static. The agents.md from a year ago is not the right agents.md for today. Many of them are overly long, overly instructive, and include a lot of unccessary code bits.
I think it's useful for people using agent harness to regularly evaluate your skills, agent rules, and memory implementation to ensure there's no conflict across them all. Also, best to rely as little as possible on the agent to write its own agents.md.
It can be be tedious, but that's why agentic coding can still be considered a "skill".
The amount of cargo-culting around AI tooling and practices is so weird to me.
Why not just try and see? The fast feedback loop allow testing all kind of weird theories in a matter of 30m-1h during normal working sessions, most results are obvious
The configuration and workflow space is big, and exploring it isn't fun for most people.
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.
Not enough on its own you'd need artifacts to store contexts/TOC/lists
I think shorter the better.
also a strange finding from my own experiences: specific empirical formats seem to yield much better results. For example people often say "get this done to 100%" but I say "get this to 88.47%".
You putting “you’re an expert jerk off master” in agents.md is the same as shaman burning a bone to predict a future.
If adding something to the context doesn't help, it's only proves you're not adding the right stuff.
I'm adding pointers to specification documents, and it saves me from the /new dumb coding agent that sees your code base for the first time and knows nothing about architecture, concepts, code organisation, etc...
I'm using no cookie cutter directives though (except maybe "do not attempt to deploy, we're using CI CD to deploy" to avoid an automatic "wrangler deploy" to Cloudflare)
As the author notes in the end, it would be really interesting to do these again on more recent models. I wonder if the no context file being cheaper still stands. But then how much does the harness influence the results. It can be frustrating trying to gauge what’s influencing what and if something suddenly starts working against you.
Yes
The referenced paper says No.
The paper actually says: "We find that all context files consistently increase the number of steps required to complete tasks. LLM-generated context files have a marginal negative effect on task success rates, while developer-written ones provide a marginal performance gain."
"Overall, our results suggest that context files have only marginal effect on agent behavior, and are likely only desirable when manually written."
I say Nes.
You are absolutely right, thank you for pushing back. Upon further examination, I've confirmed that the referenced paper says no.
/s
On a second thought... The result is counter-intuitive, because writing AGENTS.md (and reading if it's generated) contributes to the context in the human. So yes, AGENTS.md probably help more than the paper says, but not the way we initially frame it.
Dunno if there's a way to test that AGENTS.md help the human more than the machine.