When AI Becomes Your Documentation's Second Reader

Our design team has maintained a component specification document for years. It records the usage rules for every component we've built — when to use this, when not to, why we made this call. It's been through dozens of revisions. Its readers, for all those years, were clearly defined: new designers joining the team, engineers confirming specs before building, me, when I need to cite a rule in a review.

Recently, I started noticing it had acquired a new class of reader.

When agents began participating in design tasks, they would read this document too — using it to evaluate whether a newly generated design was compliant. At first this seemed like it was simply "one more use case." But the more I thought about it, the more I realized the change was deeper than gaining a reader.

---

The way a person reads this document and the way an agent reads it are fundamentally different.

A person brings enormous background knowledge that isn't written anywhere in the document. When a senior designer reads "button spacing 16px," they automatically understand the history behind that number — maybe it was a team decision years ago, maybe it aligns with a larger grid system. The "why" lives in their head, not in the document. We never wrote it down because it was shared context. Everyone already knew.

An agent reading the same document has no shared context. It reads what's written. "Button spacing 16px" is a rule, nothing more — no history, no reasoning, no understanding of when the rule might have exceptions.

This looks like an "information asymmetry" problem — just write the why too, and it's solved. But I've come to think that framing is exactly the wrong one.

We tried writing more "whys" into the document. The result was a document that started to read like a team history archive — every rule followed by a backstory.

This created two new problems.

The first: the "whys" are themselves moving targets. A team's understanding of a decision evolves over time. We set 16px originally for reason A; five years later, that number still holds, but the reason has quietly become reason B. If the document says "because A" and the real reason is now "B," the document has developed a subtle kind of staleness — not in the rule itself, but in its rationale. A person reading it will naturally update their understanding. An agent reads the version on the page, always.

The second problem is more counterintuitive. When a document becomes detailed enough for an agent to execute directly, it becomes too detailed for the humans it also serves. A new designer joining the team needs "button spacing 16px, to align with our 8px grid" — one sentence. They don't need the full context of a decision made five years ago. But if the document packs in every detail to help the agent understand context, the document's readability for people goes down.

Once I saw this in the component spec, I started looking at other things the team uses every day — task boards, requirement lists, review notes.

These tools have something in common: they were designed under the assumption that the reader is a human. A card on a task board assumes "the person who opens this card knows how to read the information on it." A requirement list assumes "the person reading this has enough background to understand what each requirement is actually asking for."

When agents start using these tools, those hidden assumptions are exposed for the first time.

The parts of these documents that were written loosely — colloquial, context-dependent, relying on the reader to fill in gaps — become especially fragile in front of agents. People have memory and experience. An agent either has no idea what "last time" refers to, or it makes an inference from what it can retrieve — which may or may not be right, and probably won't be checked.

All the "vague but workable" parts of these tools were built on the assumption that human comprehension fills the blanks. The moment a reader enters who can't fill those blanks, the blanks stop being invisible.

I eventually arrived at this: these tools didn't just gain another user. Their nature changed.

These two registers aren't the same. The first allows for gaps, because humans fill them. The second doesn't, because nothing fills them — unless the gap is explicitly designed as a moment for the agent to ask.

What's actually happening is that these tools are shifting from being "reference materials maintained by humans, for humans" to being "protocols co-maintained by humans and agents, readable correctly by both." They still look the same — documents, boards, lists — but what they're responsible for is entirely different. And most teams are still writing and maintaining them as if they're just documents.

I've been experimenting with one approach in my own projects: separating what I think of as the "default context" from the "complete record."

This split maps onto the two kinds of accuracy I described: the stripped version handles "reliably executable without human intervention." The full version preserves "meaningful to humans" — and provides depth for agents that genuinely need it.

Whether this works as well for process tools — task boards, requirement lists — as it does for rule-based content like specs, I'm still watching. But in the spec domain at least, the split has let the two audiences' needs stop competing. The stripped version doesn't get bloated to serve agents. The full version doesn't get compromised for readability.

The underlying realization: there's no single document that's optimal for every reader. There's a default context for when you need things to run without asking, and there's a deeper record for when someone — human or agent — needs to understand why.