Design teams take documentation seriously. Component usage guidelines, for instance — when to use something, when not to, why it was decided that way. These documents have existed for years, updated over years. The audience has always been clear: designers joining the team, engineers checking specs, designers making significant decisions that need to be recorded.

In the AI era, that audience gained a new member. When an Agent participates in a design task, it reads the relevant documentation to understand what rules to follow. That shift directly determines the quality of what the Agent produces.

01

One Document, Two Ways of Reading

The way humans read documentation and the way Agents read it are fundamentally different.

When a human reads a spec, they bring a lot of background knowledge that isn't written down anywhere. A doc says "button spacing: 16px." An experienced designer reads that and immediately thinks about why — maybe it came from a team discussion a few years back, maybe it aligns with a larger grid system. That "why" usually never makes it into the document, because for humans it's shared context. Everyone already knows, so no one writes it down.

An Agent reading the same document has none of that. It can only work with what's actually written. "Button spacing: 16px" is a rule. That's it. The Agent has no way to judge when that rule might need to be broken.

This sounds like an information asymmetry problem — just write the exceptions into the document, right?

But writing more doesn't fix it either.

First, there's the maintenance burden. A team's understanding of any given decision evolves over time — exceptions emerge, contexts shift. Keeping a document that tries to capture all of it current is expensive work.

The less obvious problem: pack in every detail, and the document becomes harder to read for humans. The very people it was originally written for start to lose the thread.

What we actually need is a better knowledge base and documentation system — one that works for both humans and Agents.
02

What This Shift Actually Means

For human readers, documentation serves judgment. Not just design specs — task boards, requirement lists, review notes. All of it exists to help people make the right call.

What Agents need is different: a basis for execution. An Agent reads what's written and acts on it directly — generating proposals, making decisions. Its accuracy depends on being able to do that correctly without someone intervening at every step.

I tried something in my own projects.

I split the documentation into two layers: an Agent version and a full version.

Two layers — Agent version and full version
Agent version Condensed — core rules only, no background, no history. "Button spacing: 16px." That's the whole entry, no "why." Loads automatically every time the Agent starts working, as its default context.
Full version All the background, historical decisions, and edge cases ever discussed. Lives in a separate path, doesn't load automatically. Both humans and Agents can pull it up when they need it — when the condensed rules don't cover a situation, or when a new designer wants to understand the reasoning.

This split roughly maps onto the two kinds of accuracy I mentioned earlier. The condensed version handles "can this be executed correctly without someone watching." The full version preserves what's meaningful to humans, and gives the Agent somewhere to go when it needs more context.

I haven't applied this approach everywhere yet — mainly to rules-based content like design specs. Whether it makes sense for process-based content like task boards and review notes, I'm still figuring out.