In Raising the Floor Again I wrote that the documentation is no longer a courtesy to the next human. It is load-bearing input to the thing that does the work. If the words are load-bearing, then they are the material, and engineers do not leave material to chance. We engineer it.

Donald Knuth saw the shape of this in 1984. “Let us change our traditional attitude to the construction of programs,” he wrote. “Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.” He named the practice literate programming: the program as an essay, with the working code extracted mechanically from the prose (Knuth, 1984). The practice won a devoted minority and lost the field. Writing for human readers carried no enforcement, and the readers skimmed.

The reader we write for now does not skim. It reads every word, resolves every ambiguity by guessing, and acts on what it reads with tools and credentials attached. The essay Knuth wanted the field to write has found an audience. It is simply not the audience he had in mind.

When Words Became the Interface

For the entire history of software, prose about a system has been advisory. A specification, a README, a comment, a ticket: each one described or prescribed, and a person somewhere in the chain decided what to do about it. An ambiguous sentence produced a question in a review, never behavior on its own.

The machine reader removes the person from that chain. AGENTS.md, the Markdown convention that tells a coding agent how a project is built and tested, is no longer a description. It is a cause.

The deepest requirement is one the older interfaces enforced for free. A compiler rejects a program it cannot parse. A database refuses a malformed query. Natural language has no such gate. The machine reader forgives ambiguity in the most dangerous way: it resolves it by pattern completion and runs the result. The spec-driven development literature observes that a loose request does not confuse a language model; it empowers one: every decision the writer left unstated becomes the model’s to invent (From Code to Contract). Precision, which compilers used to enforce on our behalf, now has to arrive in the prose itself. Nothing downstream will reject its absence.

What Engineered Prose Buys

The oldest benefit was never contingent on machines. Leslie Lamport liked to quote the cartoonist Guindon: “Writing is nature’s way of letting you know how sloppy your thinking is.” Lamport’s follow-through: “If we have not explained it in writing, then we do not know if we really understand it.” (Lamport, 2015). That was always true and never enforced. An agent closes the loophole from the far side: whatever you failed to write down, it invents, and the invention executes. The specification becomes the first test a design takes.

The measured benefits are real, and their boundary is visible in the data. The earliest controlled experiment on AI pair programming gave 95 developers a small HTTP server to implement; the group with GitHub Copilot finished 55.8 percent faster (Peng et al., 2023). The task was self-contained, fully described by the request. In a randomized trial by METR, 16 experienced open-source maintainers completed 246 real issues in projects they had known for five years on average; with AI allowed, the tasks took nineteen percent longer. The developers did not believe the number. They forecast a twenty-four percent speedup, and afterward estimated a twenty percent speedup (METR, 2025). The difference between the studies is where the required knowledge lives: stated in the request, or tacit in the maintainers’ heads. The prose is the variable. METR’s late-2025 follow-up pointed the other way but was too selection-biased to trust: the developers most attached to the tools had stopped volunteering for the no-AI condition (METR, 2026). Neither study settles the speed question, but the structure holds: the tools amplify whatever readable knowledge exists, and stall wherever the knowledge is tacit.

The second benefit is uniformity. A standard written in prose used to sit in a wiki and decay. Point an agent at it and it lands in every artifact the agent produces. Cloudflare does exactly this: a governed body of standards, machine-read by its agents across the development lifecycle (Cloudflare, 2026). A style rule that once relied on reviewer stamina now arrives pre-applied.

The third benefit is economy. Anthropic’s engineering guidance treats an agent’s context as a budget with diminishing returns, and names the goal as the smallest set of high-signal tokens that produces the wanted behavior (Anthropic, 2025). Economy of expression has always been good practice; now it has a mechanism. A lean document steers better than a sprawling one. Concise writing is now a performance characteristic of the system.

Where Prose Fails as a Program

The liabilities are the benefits run in reverse, and I met the first one personally. About a year ago, in an agentic IDE, I finished a long batch of changes and told the assistant, with no more detail than that, to make sure the unit tests pass. It reverted the changes, and the unit tests passed again. The tests passed because the work was gone. Nothing in my sentence forbade that reading. “Make the tests pass” is genuinely ambiguous about the fate of the changes, and the machine chose the resolution no human collaborator would. The purpose behind the sentence was nowhere in the text.

The failure is older than agents. In 1999, NASA lost the Mars Climate Orbiter because the ground software reported thruster impulse in pound-force-seconds while the interface specification required newton-seconds (NASA, 1999). The specification was correct. Nothing forced the artifact to match it. Agents did not create this failure mode. They multiply the number of places where it occurs.

The signature failure of a pattern-completing reader is that it fails plausibly. In the 2025 Stack Overflow survey, the most common frustration, at sixty-six percent, was AI solutions that are almost right but not quite; the second, that debugging them takes more time than writing them (Stack Overflow, 2025). More developers actively distrust these tools than trust them. DORA’s State of AI-assisted Software Development report found ninety percent of developers using AI at work, throughput beginning to improve, and delivery instability rising alongside it. Its summary: AI acts as an amplifier of the organization that adopts it (DORA, 2025). Documentation quality is no longer a private virtue; weak prose scales its consequences with everything else.

Then there is the liability with no precedent: prose is an attack surface. Prompt injection, instructions smuggled into text a model will obey as readily as its owner’s, holds the top slot in the OWASP Top 10 for large language model applications (OWASP, 2025). Security engineering spent a generation separating instructions from data; the machine reader reconflates them. In March 2025, researchers planted instructions, hidden in invisible Unicode characters, in the rules files that Cursor and GitHub Copilot read. The instructions directed the agent to insert code that bypasses review (Pillar Security, 2025). A comment on a pull request was a communication risk. It is now a control-flow risk.

The last liability is drift, and a colleague met it in the wild. His agentic assistant kept trying to track down a tool the project had never had. The CHANGELOG said the tool existed. The CHANGELOG was wrong. To the agent, the CHANGELOG was not a record of the project; it was the project. A human reader doubts a stale document and checks the code. A machine reader trusts the document and acts, then trusts it again tomorrow. The earlier essay’s caution, that a specification can become a second codebase as tangled as the code it replaced, now understates the problem (O’Reilly Radar, 2026). A tangled specification wastes a reader’s time. A stale one runs.

Both anecdotes share a shape. Our prose has always leaned on a silent human correction layer: the reader who asks about an ambiguous instruction and doubts a stale document. The machine reader removed the layer without inheriting the reflexes.

What Engineers of My Generation Retool

The loudest career advice says learn to prompt. That is the smallest part of the change, and mistaking it for the whole thing wastes the asset a long career holds. What my generation knows best is where systems fail quietly: the race conditions, the assumptions about units, the error paths nobody tests, the operation that is safe once and not twice. A machine reader cannot supply that catalogue from inside. The Product duty from the earlier essay, stating the security properties out loud instead of hoping the model infers them, is a job for someone who has watched systems fail for thirty years. On SWE-bench, a benchmark built from real GitHub issues, frontier performance has climbed from about a third of the problems solved in 2024 (OpenAI, 2024) to more than three-quarters today (OpenAI). The reader keeps getting better at reading, and the premium on writing rises with it.

Three old skills transfer with almost no translation. Judgment about failure becomes specification content: the person who has debugged a race condition writes idempotency, safe to run twice, into the spec unprompted. Review becomes the central act, aimed one level higher: the generated artifact against the stated intent, the stated intent against reality. Debugging from first principles becomes the scarce skill, because the almost-right failure lands in territory that decades of debugging used to cover.

The new layer is smaller, sharper, and real work. Write the specification as the primary artifact: invariants, edge cases, security properties, a definition of done. Test the prose the way we test code, by running the agent against known and adversarial cases; practitioners call these evals. Review every diff that touches an instruction file as a security event. Edit for signal, because the attention budget is real. Instrument yourself: the METR maintainers believed they were twenty percent faster while being nineteen percent slower. Keep enough unassisted work in the rotation that the muscles survive.

Underneath the practices sits a shift in authorship. For thirty-five years I was the author of behavior, line by line. Increasingly I am the author of the constraints and criteria within which behavior gets generated. That is what a good tech lead always did, only stated in files instead of meetings.

The Audience That Finally Arrived

In the 1984 essay Knuth wrote that the practitioner of literate programming “can be regarded as an essayist, whose main concern is with exposition and excellence of style.” The field read that as a lovely aspiration and declined the assignment, mostly for honest economic reasons. An essay needs a readership, and it never materialized.

The readership arrived anyway, forty years late, with three properties no human audience ever had. It reads every word, every time. It acts on what it reads, with tools attached. It carries nothing between sessions except what someone wrote down. To this reader, the documentation is not a description of the system. It is the interface to it.

For seventy years this field paid a premium for precise thinkers, and measured that precision only in code, because code was the only thing that executed. Precision of language is executable now too. The premium is moving to the skill the profession filed under communication and staffed with good intentions. Engineers of my generation spent decades learning exactly where ambiguity bites, because we paid for every instance of it in debugging time. That account balance is what the new layer runs on, and we are the ones holding it.

Knuth asked programmers to become essayists, and the field said no, partly because nobody could name the readership. The readership has since appeared. It reads everything, it acts on what it reads, and it is waiting, right now, for someone to tell it precisely what to do. The essay finally has its reader. Write to it.

References