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 new interface has one requirement the older ones 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. A practitioner guide to spec-driven development describes what a loose request produces. The model guesses, and the result is often “plausible-looking code that makes dozens of unstated assumptions,” many of them wrong (Piskala, 2026). 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.

Speed is the second benefit, and the data shows where it stops. An early 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, an AI research nonprofit, 16 experienced open-source maintainers completed 246 real issues in projects they had worked on 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).

Among the likely causes METR identified was implicit repository context: the maintainers relied on undocumented knowledge of their own code, and the AI lacked it. One developer’s example: the model did not know about “this weird case of backwards compatibility.” A follow-up begun in August 2025 hinted at a speedup, but METR judged it unreliable: the developers keenest on the tools had stopped volunteering to work without them (METR, 2026). None of these studies settles the speed question. The evidence so far fits one pattern: the tools amplify whatever knowledge has been written down, and stall wherever it stays tacit.

The third 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 this with the Codex, a governed body of engineering standards that its agents apply at the point of work, including in code review (Cloudflare, 2026). A style rule that once relied on reviewer stamina now has a reviewer that does not tire.

The fourth 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 has become 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 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 was that “debugging AI-generated code is more time-consuming” (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 respondents using AI at work, throughput beginning to improve, and delivery instability rising alongside it. Its verdict: AI is “an amplifier, magnifying an organization’s existing strengths and weaknesses” (DORA, 2025). Documentation quality is no longer a private virtue; weak prose scales its consequences with everything else.

Then there is the liability security engineers will recognize: 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 merges them again. In March 2025, researchers at Pillar Security hid instructions in invisible Unicode characters inside the rules files that Cursor and GitHub Copilot read. The hidden instructions directed the agent to insert malicious code that slips past ordinary code 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 ran into it. 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 knows that catalogue in general, not which entries threaten a given system. 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.

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 almost-right code fails in the subtle ways that decades of debugging teach a person to find.

The new layer is smaller and sharper, and it is 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 context budget is finite. 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. An essay needs a reader who reads closely, and that reader never materialized.

That reader 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. Now the reader he could not promise them is waiting for someone to tell it precisely what to do. The essay finally has its reader. Write to it.

References