Write for the Codec

Nobody reads your documentation. Both ends are a model now, and the file between them is a wire format.

This content is not intended for human consumption. This page explains why.

Nobody reads your documentation. Both ends are Claude now.

Watch the chain in any AI-heavy team this year. You explain intent to your agent in a messy conversation. The agent writes the doc. A colleague never opens the doc; their agent reads it and renders an answer into their context, at their level, in their language. Two humans communicated. Neither touched the file.

That file is no longer a document in any meaningful sense. It is a wire format between two codecs, and the moment you see it that way you inherit an entire engineering discipline that “write better docs” advice never had: encoding loss, schema drift, checksums, round-trip tests. Documentation stopped being a deliverable. It became a protocol. This piece is about what that buys you and what it breaks.

The deliverable is dead

For seventy years the doc was the product. You wrote it for a reader, and the canon of technical writing (audience empathy, narrative flow, progressive disclosure) optimized for that reader’s experience on the page.

That reader has moved. They now sit behind their own model, which reads the doc for them and re-renders it into whatever they need: three bullet points, a code sample, an explanation pitched at their expertise. The doc itself became an intermediate representation, a compiled artifact between two translation steps. Nobody consumes it raw, the way nobody reads bytecode.

This flips the quality metric. “Is it pleasant to read” stops mattering at the artifact layer. The question that replaces it: does it decode back to the original intent? A beautifully written doc that decodes wrong is a worse doc than an ugly table that decodes right. Half the technical-writing canon targets a reader who no longer exists at that layer. The reader moved to the decode edge, and the doc must now serve the codec in between.

The stack

Name the layers, because each one fails differently.

Intent. The human’s actual goal, held in a head. Never serialized directly, only ever encoded.

The encode hop. Person to model. The first lossy step: what you said versus what you meant, the constraint you thought was too obvious to state, the context you forgot you had. The model writes down what it inferred.

The wire. The doc. The only durable, inspectable, versionable artifact in the whole chain. Everything else is ephemeral conversation.

The decode hop. Model to reader. The second lossy step, plus personalization: the reader’s agent fills gaps from its priors and presents the result with fluent confidence, whether or not the gaps were filled correctly.

The split that makes this the async layer. Tool calls and MCP are the synchronous protocol, request and response, machine to machine in milliseconds. Docs are the store-and-forward layer: written once, decoded many times, by decoders that do not exist yet. Asynchronous, one-to-many, and unversioned. That last property is the problem the whole piece funnels toward.

None of this is speculative. The protocol already evolved in the wild, unnamed. AGENTS.md sits in over 60,000 open-source repositories, read by twenty-plus tools, and its own site states the frame plainly: “a README for agents.” Jeremy Howard’s llms.txt proposal (September 2024) asks websites to publish an LLM-friendly markdown file precisely because the consumer of your content is now a context window. CLAUDE.md, skill files, cursor rules: all wire formats, all evolved rather than designed, all already exhibiting the traits this piece predicts. Front-loaded constraints. Explicit conventions. Zero narrative.

Two hops, compounding loss

Each hop loses information silently. The encode hop drops the obvious-to-you constraint. The decode hop invents a plausible replacement. Neither hop announces the substitution, and the errors compound: a doc that is 95% faithful, decoded at 95% fidelity, delivers 90% and shows no seam.

The protocol framing earns its keep here, because protocols have checksums and prose does not. Three that work today:

The round-trip test. Give a fresh agent the doc alone and ask it to re-derive the requirement. Diff the result against the original ask. Where they diverge, the wire is underspecified. This is loopback testing, applied to prose.

Receipts in the artifact. Every claim in the doc carries its source, or carries an explicit unverified label. This does more than discipline the writer: it transports calibration across the wire. A decoder that inherits “verified against X” and “assumed, not checked” can carry that confidence through intact. A decoder handed uniform confident prose invents its own calibration, badly.

Explicit gap markers. An agreed token for “this is unknown” ($UNKNOWN, in a convention I put into production in July 2026) beats fluent gap-filling, because the single most dangerous property of an LLM decoder is that it fills silence with plausibility. Mark the silence.

I can offer live evidence that the loss is real, from the week this piece was first drafted, in July 2026. A research pipeline (searcher agents, extractor agents, verifier agents) pulled usage statistics for this article’s sibling piece. Hand-checking the output against primary sources caught two silent errors. An extractor read a bar chart and attributed 9% to the wrong task; the correct figure was 7%, and the 9% belonged to the neighboring bar. A summarizer answered a base question backwards, reporting task percentages as “share of users” when the primary’s own chart caption said share of all adults. Both errors arrived fluent, quoted, and plausible. Both died only because the numbers were round-tripped to source. Two codec errors, one week, one small project. Scale that to an organization’s documentation surface and the case for checksums makes itself.

The deeper point: the wire is the only place verification can attach. Both hops are ephemeral. The conversation that encoded the doc is gone; the rendering the reader saw is gone. The doc is the audit surface, the one artifact where receipts, gap markers, and round-trip results can live. Which means the doc’s job description changed. Its first job now is to be a verifiable record that explanations can be regenerated from.

What the wire format drifts toward

Once both endpoints are machines, selective pressure on the format changes direction. Four drifts, all already visible in the evolved conventions:

Density rises. Human-optimized prose is a low-density encoding, padded with comprehension pacing the codec does not need. Machine-facing files compress: tables, lists, invariants.

Ambiguity becomes hostile. Every underspecified sentence is a branch point at decode time, resolved by a model’s priors instead of the author’s intent. Explicit beats elegant, every time they conflict.

Structure beats narrative. Front-load the constraints. State the conventions as conventions. A narrative doc buries its load-bearing sentence in paragraph six; a wire-format doc puts it in a header, because retrieval lands on headers.

Atoms beat essays. One fact per unit, addressable, linkable. Retrieval systems return chunks; a chunk of an essay is a torn page, a chunk of an atomized corpus is a complete fact. This is why every serious agent-memory system converges on atomized notes with links, and why monolithic wikis decode so badly.

One counter-pressure keeps the format from going fully machine-opaque: humans still audit the wire. When the round-trip fails, a person opens the file. The equilibrium is machine-dense and human-inspectable, which, conveniently, is also a decent description of good engineering documentation before any of this happened.

The decode edge does the audience work

Here is the liberating half. One canonical doc now yields N renderings. The reader’s agent re-renders into the reader’s expertise level, language, and cognitive style. The junior engineer gets the walkthrough; the architect gets the invariants; the non-native speaker gets their own language; the screen-reader user gets structure that linearizes cleanly.

“Write for your audience” was always a compromise with physics: one artifact, many readers, pick a compromise register and lose everyone a little. That constraint dissolved. The audience is now a variable resolved at decode time. You write for the codec; the codec writes for the audience. Authors who internalize this stop polishing register and start specifying meaning, because register is the decoder’s job now and meaning is the only thing that survives the wire.

The part nobody has solved

Natural language is a wire format with no schema guarantee, and I want to be precise about how unusual that is.

Every serious protocol negotiates. Version fields, handshakes, error responses, a NAK when the message fails to parse. The doc-to-agent wire has none of this. Two models share training distributions, and that is all they share. There is no version negotiation, and no error signal: a decoder that misreads your doc does not throw, it answers.

Worse, the decoder changes under you. A model update is a silent, global decoder swap. Yesterday’s doc decodes differently today, and nothing in the doc can even detect that it happened. Fixed corpus, drifting interpretation. We version the wire and nobody versions the codec.

The current mitigations are real and all partial. Conventions files act as informal schemas. Round-trip tests act as integration tests, and can at least be re-run after a model update. Receipts transport calibration. In short: the protocol works today because both codecs are large, tolerant, and similar to each other. That is a property of this particular moment in model training, and it is nobody’s guarantee. Nothing in the stack promises that the decoder your reader runs in two years resolves your sentences the way yours did when you wrote them.

The doc you wrote today already went through this chain at least once, whether you designed for it or not. Someone’s agent has already summarized it to someone who will never open it.

So design for it. The whole discipline compresses to three lines:

Write atoms, one fact per addressable unit.
Mark gaps explicitly; never let the decoder improvise in your silence.
Test the round trip, and re-test it when the models change.

The readers are fine, we just outsourced the reading.