A few weeks ago I wrote about being the documentation. Not the wiki. Me. The person everyone pinged because asking was faster than looking, and who quietly liked it that way.
A reader left a comment on that piece that I haven’t stopped thinking about. She’d lived the other side of it, joining a huge, tangled codebase as the new person and finding her way through it. Her point was that agents might actually make documentation better, because when an agent gets something wrong, you see it fast, and you see exactly where. Then she asked the question this whole piece is an answer to: if an agent can scrape all that knowledge, would you ask it instead of asking the person?
And she pushed my own metaphor one step further. In my version, Marcus Aurelius pays his respects to the court and goes home to philosophy. In hers, Marcus writes the documentation, and the court asks an intermediary.
I liked that so much I went and checked whether it was true.
The Intermediary Already Existed
It was. Roman emperors governed largely by letter, and they had offices to handle it. The ab epistulis managed the emperor’s official correspondence. The a libellis handled petitions from private citizens and drafted the replies. In the 170s, Marcus’s secretary for letters was a well-known orator named Alexander.
So the court already asked an intermediary. Routine questions went to the office, and the office answered in the emperor’s name.
But the book we call the Meditations wasn’t written for those offices. Its Greek title means, roughly, “to himself,” and it was almost certainly never meant for anyone else to read. The secretaries had the letters, the rulings, the record of what the emperor decided. What they didn’t have was the notebook where he worked out why.
The secretaries could answer the court. They couldn’t answer for him.
Ask the Agent for the What
Most of what I ask at work is lookup. Where does this calculation live? How does the nightly batch handle this case? Which service writes to this table?
Eighteen months into a system too big for anyone, I ask those questions. Yet, I often get a seven-word direction instead of a clear answer. “Check how the nightly batch handles it.” I spent a whole piece arguing that the direction was the generous answer.
An agent that can read the codebase is that direction, available whenever you want it, without spending anyone’s afternoon. For the what, ask the agent. I don’t think it’s close.
But there’s a second kind of question, and its answer never shows up in the code. Why does it work this way? What did we try before this, and why did we drop it? Is this rule here because a regulator requires it, or because somebody made a risk call six years ago and nobody has revisited it since?
Those answers aren’t in the repository. They live in the people who were in the room. Ask the person. Ask a model to give you judgment and you’ll get answers without the education. Ask a person where a config file lives and you’re spending their attention on something a search could have told you.
Different questions, different places to ask.
The Honest Reader
I’ve been the new person on a big system for a year and a half, and I know how bad documentation survives. It survives because new people paper over it.
A new hire reads a page that’s two refactors out of date, notices something doesn’t match, and fills the gap. Maybe from a hallway conversation. Maybe from an old thread. Maybe by asking someone who says “oh, that page is old, it actually works like this.” The gap gets filled. The page stays wrong. Nobody writes anything down, because the problem got solved, and the next new hire fills the same gap the same way.
We are very good at covering for bad documentation. We do it politely, constantly, and without noticing.
An agent can’t. It has no hallway. It wasn’t at the standup where someone mentioned the migration. It doesn’t know that everyone stopped trusting that README two years ago. It reads what’s written and believes it. But when it assumes something that was never said, it fails right there, for everyone to see.
That isn’t a flaw in the agent. It’s the most honest reader your documentation has ever had.
I wrote a while back about the person who inherits your mess: the developer opening a file you wrote, rebuilding context that lived in your head for an afternoon and then vanished. Hierocles imagined circles of people you might eventually meet. He never imagined a stranger shaped by your keyboard months before they exist to you.
Now that stranger shows up every day. Every time someone hands an agent a task in your corner of the system, your documentation gets read by someone with no social cover to offer it. If the why isn’t written down, the agent won’t know to ask. It’ll guess, confidently, and someone will end up coming to you anyway.
What the Secretary Can’t Read
The agent can only read what someone wrote. That sounds obvious, but it changes the job of the person who knows things.
I ended the original piece on writing down what only you know, “especially the parts you keep putting off. That’s usually where the pride is hiding.” I meant the pride of being needed. If it’s written down, nobody has to ask you.
An agent makes that harder to dodge. The what is getting easy to find without anyone’s help. Whatever the agent can’t answer will be precisely the part that only ever lived in your head: the why, the tried and abandoned, the old risk call. Which is also precisely the part you’ve been putting off writing.
The agent hasn’t made the person who knows things obsolete. It’s handed them a smaller, harder job. Not the lookup. The reasoning. The part Marcus kept in a notebook.
So, to answer my reader: yes, I’ll ask the agent first, for almost anything that has a location. When I need to know why, I’ll ask the person.
But the bigger change runs the other way. The court can ask the secretary now. Make sure the secretary has something worth reading.
👉 If you enjoy reading this post, feel free to share it with friends!
Or feel free to click the ❤️ button on this post so more people can discover it on Substack 🙏
You can find me on X and Instagram.