Man Who Has Never Written a README Now Maintains 2,000 Words of Instructions for His AI Agent

SATIRE — At 8:41 a.m., a man who has never written a README began revising AGENT_INSTRUCTIONS.md for the seventeenth time. The file was 2,143 words long, contained a table of prohibited adjectives, prescribed the agent’s emotional relationship to feature flags, and opened with a section titled “Non-Negotiable Principles,” a phrase he had previously reserved for telling coworkers that code should explain itself.

For most of his career, Darren Vole had held a clear position on documentation: if someone needed instructions to run the service, they should simply inspect the seven shell scripts, two obsolete Dockerfiles, and the Makefile target named fix-it-for-real-this-time. A README, in Darren’s view, was a fragile duplicate of reality. Reality was the repository, plus whatever Maya from infrastructure remembered from the outage last spring.

Then Darren installed an AI coding agent. The agent asked one innocent question—“How should I run the tests?”—and he experienced what he later described to nobody as an architectural awakening.

The document begins where all good engineering begins: with exceptions

The first version of Darren’s instructions was 96 words. It said: “Use good judgment. Follow existing patterns. Run tests.” The agent followed an existing pattern into a legacy directory, ran a test suite that had not passed since the company’s second office had a ping-pong table, and changed a shared utility named normalize that was imported by 438 files and one billing workflow maintained by a contractor called only “G.”

Darren responded as any practical engineer would: by adding a 14-part governance framework.

• Never modify shared utilities unless explicitly instructed, except when the utility is clearly wrong, except when changing it would create compatibility risk.
• Do not use any, unless the surrounding code uses any, in which case improve the type situation conservatively but do not introduce a type migration.
• Prefer small diffs, unless a broad refactor is necessary to preserve consistency, in which case explain the refactor before doing it and wait for approval unless working autonomously.
• Run the relevant tests, defined as tests relevant to the change, except when those tests are slow, flaky, unavailable, misleading, or spiritually inappropriate.

The document includes a mandatory reconnaissance phase. Before touching code, the agent must inspect architecture notes, conventions, adjacent modules, package scripts, CI configuration, recent commits, open pull requests, and “the general vibe of the codebase.” Darren has never conducted this procedure himself. He generally opens the file mentioned in the ticket, changes the first thing that looks guilty, and waits for continuous integration to provide a more specific theory.

A workflow emerges

By Tuesday, Darren had created a command called npm run agent:briefing. It assembles repository guidance from 11 files, inserts the current branch name, checks whether any filenames contain the word deprecated, and prints a warning if the agent is operating within 50 lines of the payments module. The warning is 312 words. It begins, “This is not an invitation to be creative.”

npm run agent:briefing -- \
  --task "add invoice export" \
  --risk-level "please do not rediscover accounting" \
  --require-plan \
  --forbid-heroics

His coworkers initially mistook the file for an onboarding guide and praised its clarity. Darren corrected them. This was not documentation. Documentation was something you wrote for humans, who should already know better. This was a precision operating manual for a probabilistic text engine with shell access, a credit card on file, and an unwavering willingness to rename every id in the monorepo to entityIdentifier.

The agent receives a philosophy minor

The current draft devotes 184 words to comments. Comments should not restate code. Comments should explain why. But they must not mention historical context unless verified. They should be concise, except for non-obvious decisions, which should be explained fully enough for a future maintainer to understand the trade-off without becoming emotionally attached to the implementation.

There is also a section on commits. The agent must make atomic commits, unless atomicity would obscure the narrative of the change. Commit messages must use the team’s preferred format, which Darren has defined as “clear but not bureaucratic.” Examples are provided. The examples contradict each other. One says to use imperative mood. Another says the imperative mood feels “too commanding for maintenance work.”

At 1:16 p.m., the agent produced a six-line patch and a concise explanation of why it had not modified the billing code. Darren read both carefully, then added a new instruction requiring agents to distinguish between “not touching billing” and “declining to touch billing,” because the latter sounded passive-aggressive.

The repository remains undocumented

Meanwhile, the project README still says only: “Install dependencies and run it.” The setup requires a private package registry token, a local database initialized from a backup stored in an internal drive, three environment variables whose names changed during a rebrand, and a background worker launched from another repository. Darren plans to fix this after the agent guidance reaches a stable 3,000 words.

The guidance is not without value. It has forced Darren to name assumptions that previously lived in his head, describe test expectations that previously arrived as pull-request comments, and admit that “follow existing patterns” is not a specification when the existing patterns are three competing mistakes preserved in version control.

At 5:47 p.m., Darren commits another update: docs(agent): clarify what 'minimal' means. The diff adds 287 words. The final line says, “If ambiguity remains, ask a question before proceeding.” It is, despite everything, the first useful instruction anyone has written for the repository.