Why AGENTS.md Is Not Always Needed

The internet saw this paper and suddenly started doubting whether writing AGENTS.md is necessary at all. Here is one take, here is another, and I probably missed a few more. I had a note on this topic sitting in my drafts for a couple of weeks already, so let's discuss it.

In short, the paper says that agents produce roughly similar results with and without AGENTS.md. If the file is generated by an agent, outcomes are worse than having no file. If it is written by a human, outcomes may be slightly better. But in both cases you add maintenance cost for yourself and extra research cost for the agent (time and tokens), because you loaded it with more context.

My own note was basically this: never use the agent /init command; it generates obvious slop. If an agent can write that document in a minute, it could also do fine without it and figure things out while working on the actual task.

But these discussions can lead to an overgeneralized conclusion that no documentation for agents is needed at all, including skills. And those are not exactly the same thing, at least when we are not talking about useless skills that only repeat what the model already knows.

When we write docs, we deliberately trade flexibility for repeatability and for giving the agent a clear starting point without extra grepping. Could it figure this out on its own? Usually yes. How quickly would it get there? Unclear. Could it choose a reference that you would consider the wrong one? Absolutely.

So I treat AGENTS.md and skills as a "temporary" patch for the fact that models still cannot quickly understand our legacy projects. Or as a way to describe tacit knowledge.

Yes, ideally we should rewrite code until it becomes unambiguous and never sends models down the wrong path. But we still need to live and ship right now. So these artifacts are useful, and we need to learn how to maintain them so they stay resilient and describe ideas, goals, and principles rather than snapshots of current implementation. The machine can handle the current state - just give it more ways to verify and self-correct.

P.S. Let's agree on this: mentally append "same for humans" to every post, and I will stop repeating it explicitly.