The Second Reader

Reflections | Business Evolution

References: 10x Speed, Zero Structure

Documentation was written for the next person who'd need to understand a decision. Increasingly, that person isn't a person.

Something quietly changed about who reads documentation first, and most teams haven't noticed. I touched on it as an asterisk in my last note. It's a bigger shift than a footnote, so I want to sit with it properly.

Documentation never existed for its own sake. It existed so that someone who wasn't in the room when a decision was made could still understand why.

That someone was always assumed to be human. A new hire. A teammate six months from now who's forgotten the context. You, eighteen months later, looking at your own code and wondering what you were thinking.

Everything about how documentation got written followed from that assumption — prose, narrative, "here's the story of why we did it this way." Written to be read once, slowly, by someone building a mental model from scratch.

That assumption doesn't hold anymore, at least not as the default.

On the team I'm on now, the first reader of most documentation is an agent: a skill file, an MD file, a set of instructions sitting in the repo that gets loaded before a human ever opens it.

The human is now the second reader. That sounds like a demotion. It isn't. But it does change what you owe them.

An agent wants structure: clear, scoped, unambiguous instructions it can act on without inferring intent from tone. A human wants narrative: context, reasoning, the story behind a decision. Try to serve both in one document and you usually serve neither.

Imagine a team that has gone SSO-only for login.

Written for the agent, the decision looks like this:

• All authentication goes through the SSO provider

• Never add password fields or local credential storage

• New login flows extend AuthGateway

Written for the human, it might read like this:

We went SSO-only after a security review stalled a customer deal. Local passwords weren't a technical problem. They were a sales problem.

Both are true. Neither replaces the other.

The first tells you what to do. An agent can act on it a hundred times a day without ever asking why.

The second tells you when the rule stops applying. If the customer requirement disappears, only the story tells you the rule can too.

An agent following the first version is perfectly obedient. It will also defend the rule long after anyone remembers what it was for.

The upside is real, not just theoretical.

Documentation written as structured context (how a team names things, where decisions live, which patterns to follow) gets produced almost as a byproduct of working with these tools at all. Nobody has to remember to write it up afterwards. It exists because the agent needed it to do the work.

That inverts the old failure mode. Documentation used to lapse because writing it was a separate, deprioritised task. When it's load-bearing for the tool you use every day, it stops being optional.

Is that enough? Not quite.

Here's a failure I keep seeing, and it's never dramatic.

An agent needs to format a date, or normalise a string, or parse a response. It looks around, doesn't find a helper it trusts, and writes a small, clean utility function. The code is fine. The tests pass. The review takes a minute, because there's nothing to object to.

Do that a few hundred times and the codebase fills up with near-identical helpers. Same job, slightly different edge cases, living in nine different files. Nobody made a bad decision. Every single one was reasonable.

Nothing in the repo told the agent where shared code lives, or that it should look before writing. A human who'd been around a while would just know. The agent only knows what it's given.

The missing sentence was one line: "Shared helpers live in /shared. Search there before writing a new one, and if you write one that's used twice, move it there."

Look at what was missing in each example. With SSO it was the why, the story that tells you when a rule can change. Here it was the map, what the codebase already has and where it lives. A human who's been around a while carries both without thinking. An agent carries neither unless someone writes them down.

Structure is cheap now. Why and map are what's left, which is the same point I made in Code is Cheap, Context is King.

So what do you actually write down?

If the pattern is visible in the code, don't write it down. The agent will find it.

Write the sentence it would confidently get wrong:

• The naming convention that looks inconsistent but isn't

• The module that's ugly on purpose

• The shortcut that's fine here and a disaster two folders over

That list is short. It's also the most valuable documentation your team owns.

Less narrative prose explaining the obvious. More precision on the judgment calls that a pattern-matcher gets wrong by default.

These sentences belong in the agent's file. That's where they do their work.

But attach a one-line reason to each: "Search /shared before writing a helper. Duplicates drift apart, and nobody ends up knowing which one is right."

The agent can follow a rule without its reason. The second reader can't question one..

A rule with no reason can only be obeyed, or quietly deleted. A rule with a reason can be questioned, which is the only way it ever gets retired on purpose. That's the job the human has now: not to read the instructions in order to follow them, but to audit them.

The practical shift is smaller than it sounds. Before writing anything down, ask who's going to read it first.

If it's an agent, write structure: scoped, explicit, built to be acted on, with the reason attached. If it's a human trying to understand a judgment call, write the story. Most documentation needs both, in the right order, not one bloated document pretending to be both.

Documentation isn't becoming less important because AI can infer more. It's becoming more important, for a different reader, in a format most teams haven't adjusted to yet.

Documentation used to be how you learned what to do.

Now the agent handles that part. The human reads it for something else: to learn what to question, starting with which rules still deserve to exist.