alt Hacker NewsThe problem with giving precedence to documentation over memory is that the documentation has to actually exist and it has to be the most accurate representation of reality. As soon as documentation becomes fragmented and out of date, memory of some kind becomes a necessity, even if this means an agent writing their own documentation as memory. I've yet to work on any team where the documentation was even close to being reliable enough without the need for cross-checking, asking those with intimate knowledge, and ultimately interim memory to make sense of it all. This is why "the code is the documentation" can often work better for agents than actual documentation written by/for humans. Humans have proven time and again to not care about documentation unless there is a profit motive for said documentation.
This is a problem when humans are responsible for keeping the docs up-to-date. But if you're doing development with agents, it's the agents' job to keep it up-to-date. And as long as your AGENTS.md instructions are clear about the process for this, I find that it just happens automatically. It takes a few tries to get the instructions right, but then documentation becoming fragmented or out-of-date just stops being a thing. Of course, this relies on all team members using the agent.
"Code is the documentation" doesn't solve the problem in my experience. Because what happens is that you still need a lot of "why" comments in the code, and then these go stale, so you still have the same problem you have to solve. And so I find that markdown documentation is a lot easier to organize and review in a structured hierarchical way in one place, than code comments sprinkled across the repo.