Put a structured header on every document, and make agents read the header before the body. That is the whole convention. Every doc in our repo carries frontmatter with three fields: a description, a status, and tags. An agent scanning the repo reads those headers first, decides relevance from the description, and opens a full body only when the header routes it there.
The payoff is context economy. An agent deciding relevance from a 60-word description spends a fraction of the tokens it would spend reading bodies, and the savings compound. Because headers are cheap, the agent can hold the whole doc map in context at once. It sees the shape of everything we have written before it commits to reading any of it.
Why bodies are the wrong default
An agent's context window is a budget. Every body it opens crowds out something else: the task, the code, the other docs it has not read yet. When the default is "open the file and read it," even a modest repo is too big to survey. The agent samples a few files, guesses at the rest, and misses the one doc that mattered.
Headers flip the default. Each field answers one routing question, and the agent only pays for a body when the header says the answer is inside.
| Field | The question it answers |
|---|---|
| description | Is this doc relevant to the task at hand? |
| status | Is this still true, or has something replaced it? |
| tags | What does this doc connect to? |
Superseded means do not act on this
Docs rot quietly. A plan gets replaced, a decision gets reversed, and the old file sits in the repo looking exactly as authoritative as the new one. A human skims the date and gets suspicious. An agent reads confident prose and believes it.
So when a doc is replaced, we mark it superseded in its header. An agent reading headers first hits that marker before it sees a single stale claim, so it never acts on retired truth. The header is not a summary of the body; it is a gate in front of it.
The same idea, pointed outward
This blog applies headers-first to visitors, not just to our own agents. Our /llms.txt lists every post with its bottom line, so an agent can survey the whole site in one read. Our /agents.md tells a visiting agent how the site is organized and where to look next.
That is the same move as answer-first writing: state the verdict up front so the reader can decide whether the rest is worth their time. A description field is an answer-first sentence for a whole document. And because this blog is MDX in a repo, each entry carries the same frontmatter discipline our internal docs do; the publishing pipeline and the doc pipeline are one habit, not two.
We feel this inside the harness every day. Judges, integrators, and candidate agents in a Fusion run all navigate the same repo under the same reading contract: headers first, bodies on demand. When a judge verifies a criterion, we want its context spent on evidence, not on wandering through files that were never relevant.
Headers as the interface
We expect more of our docs' readers to be agents than humans, and we are starting to treat descriptions the way we treat function signatures: a small, stable surface that other software depends on. The next step is enforcement, linting headers the way we lint code, so a missing description or an unmarked superseded doc fails the build instead of failing an agent mid-task. When a doc map is machine-checkable, routing stops being a courtesy and becomes a contract.