Posts like this frustrate me. Not because of what they ask, but because of what they incorrectly assume. They assume that documentation can provide enough context, and that human knowledge is not needed.

Every bit of written documentation can and will be misinterpreted. And perfect clarity is impossible. A well-written ADR does not eliminate all ambiguity, because there is too much cultural context around the writing of the ADR that attempting to read it from some other cultural vantage point leads to bad assumptions. We can find this basic lesson from reading law (2nd, 14th amendments to the constitution), history (what did happen after Muhammad died?), philosophy (what in the world is Plato's cave talking about?), or theology (how should we translate Ephesians 5:22-33 and what does that mean) outside its original context with other people.

Just writing things down and thinking an AI is going to later perfectly understand what the intent of the author is... patently ridiculous. I do not intend to dismiss the idea that we should probably document more, but the idea that the AI can just take our documentation and competently understand all the decisions represented in them is ludicrous.

Very, very few of these organizations have ever known, and fewer still have ever cared, about their Sarahs.

This isn't the end of Sarahs. Sarahs have never had their time or place beyond immediate teams, many of which have used Fight Club rules when it came to their Sarah: Never talk about Sarah, especially not to the boss. Other, non Fight Club rules: When Sarah is away, cover as best you can. Change jobs before Sarah retires. It is not the end, because the time of Sarahs never began.

So I agree with ";dr" comment, but it would apply had this been written by a human, by AI, by a super-intelligent shade of blue, or a small furry creature from Alpha Centauri.

the agent has the operator, and the operator has a sarah

i have spent a lot of time answering colleague's agent's questions as a sarah.

my thought has been to try to commit any of the answers to those questions into the relevant codebases so that they become findable.

same with anytime i have to give the agent extra context about some code. The end goal being that as much knowledge as possible is out of my head, and put nearby the code where its most useful

It turns out wrapping the patch with these things makes the patch better. Plus, you have docs. All this goes in the PR.

Humans think docs cost/waste time. Agents not only don't care, but code better when doing SDLC (because once you get rid of the cult ceremonies, the core principles work). And so do humans.

Maybe Sarah can write it down, and maybe so can anyone that gets an answer from her, and maybe so can the LLM.

I just think this is entirely wrong. Oral tradition is valuable because it's flexible in a way that written tradition struggles to be. Just a handful of oral-tradition decisions I routinely see that could never be written up as persistent documentation:

* The CEO said X is our top priority, but we think Y is more important and we can do it without compromising too much on X, so we're going to do both.

* Team A has a track record of quality and success, so their decisions are subject to less review and receive more deference

* Team B is sloppy and makes a lot of bad calls, so we don't trust their judgments when doing so might lead to an outage for us.