Do agents.md files help coding agents?

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".

I use AGENTS.md to make sure my agents loop effectively (tests, quality, etc). Not to describe the code / architecture.

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

On a new project I usually set up the context of the model (language to use, reason of the product/prototype, etc.) and then I tell the LLM to write a AGENT.md, STATE.md and ROADMAP.md. I don't tell the LLM what's in there because the model has it's own directive and flavor what should be in these files. The models already know the purpose of these files by themself! On a new session, I let the agent read the markdown files in order to continue with the work. Before a session ends, I let the LLM update the markdown files. Maybe one word of caution: don't switch models - it's like putting another person on a working station and ask them to continue the work of others.

Easy setup, really good outcome!

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)

I don't think this is bad research, but you have to understand how far it generalizes. I'm not saying that evals are useless, we need to do our best to produce good benchmarks. But benchmarks are always going to lag pretty far behind real world applications.

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%".

[1] https://openai.com/index/harness-engineering/

Also, there is such a thing as excessive or useless context. Personally, I like to control what the AI reads by customizing the prompt with only what it needs and nothing more.