Documentation an agent and a new hire can both use

Most engineering teams have documentation nobody reads. In an AI-native team the same documents are read constantly, by an agent, on every task, and turned into code at speed. That changes the cost and value of writing them and the cost of leaving them wrong.

The failure mode is new

An out-of-date wiki page used to be a mild inconvenience. Someone read it, got confused, asked a colleague, and moved on. The document caused mistakes only now and then.

Now the wrong instruction is loaded into a session that produces four files from it, and does so again next week, and does not ask a colleague. The number of mistakes grows with the amount of code generated. That single fact is the reason to be quick to delete documentation you are not going to maintain.

The correct response is not to write more. It is to write less, keep it correct, and put it where it will be read.

What to keep permanently loaded

Every agentic tool has a file it reads at the start of every session. Space in that file is valuable, because everything in it competes for attention with the actual task. Anthropic's own guidance is direct: keep it short and human-readable, and for each line ask whether removing it would cause a mistake, because a long file full of extra detail causes the model to ignore the real instructions [1].

What belongs there:

Commands the model cannot guess. How to run the tests, the build, the type check, the local server, the one script with a strange name.

Rules that differ from the default. Conventions your codebase uses that are not the language's normal ones. There is no value in telling a model to write clean code.

Hard constraints. What must never happen: never commit this file, never call this API from that layer, never write to that table directly.

Surprising requirements. The environment variable that has to be set, the service that must be running, the test that fails if the machine clock is wrong.

What does not belong there: a description of the architecture that the code already shows, a tutorial, anything that changes weekly, and a list of every module. That material either belongs closer to the code or should be deleted.

What to write next to the code

Three kinds of writing are worth their cost in a fast-moving codebase, and all three belong in the repository rather than in a separate system.

Why, not what. The code shows what it does. What it cannot show is why it does it that way, what was tried first, and what constraint forced the unusual design. That comment is the one thing a future session cannot regenerate, and it is what stops the next agent simplifying a workaround back into the bug it was fixing.

Decision records. Short and few, as covered in the decisions that stay with your engineers.

The runbook line per critical flow. One or two sentences on what it does, what it depends on, and how to turn it off, kept where a responder is already looking. Longer runbooks become out of date, and an out-of-date runbook leads a responder confidently to the wrong action, which is worse than having none.

The rule that keeps documents accurate

Change the document in the same change as the code, or do not have the document.

This is the only rule we have found that works at volume. Documentation kept in a separate system, updated on a separate schedule, by a person who has to remember, is documentation that is wrong within a month. Documentation in the same commit as the code is documentation a reviewer sees while looking at the change, which is the only moment anyone can tell whether it is still accurate.

The corollary is that anything you cannot commit to updating in the same change should be deleted rather than left to become wrong. Teams find this uncomfortable. It is still correct: an empty space misleads nobody, while an out-of-date page leads people into mistakes.

Write it so both audiences can use it

There is a lucky coincidence in AI-native documentation: what an agent needs and what a new engineer needs are nearly the same thing. Both arrive with no context, both need the constraints stated explicitly, and both benefit from being shown one standard example rather than given an abstract description.

So write for a capable person joining the team next week. Name specific files. State the constraint in one sentence rather than three paragraphs of context. Prefer a link to a real example over a description of the pattern, since an agent follows an example more reliably than prose, and so does a new hire.

The overlap has a practical benefit worth using: onboarding is now a test of the documentation. If a new engineer had to ask a question, the answer belongs in the file, which is also the answer the next agent session needed. Our post on how to onboard engineers fast covers doing this on purpose.

Testing your documentation

Documentation in an AI-native team has something documentation never had before: an objective test. Give an agent a task in a clean session with only your documentation and see whether the output is right.

That is a real test and it is cheap. When the result is wrong, you learn precisely which assumption was missing, because the failure shows what is missing. Do it once a quarter on a representative task and you will find that most of what you thought was essential is ignorable, and that the thing missing is a constraint everyone on the team considered too obvious to write down.

The specification does not stop being useful at launch

Most teams write a specification, build from it, release, and let it go out of date. In an AI-native team that is a bigger waste than it used to be, because the specification is the one artefact that states intent in a form both a person and an agent can use, and intent is exactly what the code cannot express.

Keeping it current does not mean maintaining a large document. It means three things. When behaviour changes, the paragraph describing that behaviour changes in the same commit. When a decision is reversed, the specification says so rather than leaving two contradictory statements for a future session to choose between. And when the specification and the code disagree, that is treated as a defect in one of them and someone decides which, rather than everyone assuming, without saying so, that the code is right.

That last habit is the valuable one. A disagreement between the specification and the implementation is information: either the software is doing something nobody asked for, or the document is describing a system that no longer exists. Both are worth knowing, and in a codebase where changes arrive faster than anyone reads them, the specification is often the only place the divergence is visible. Our post on how to keep a spec alive after the build covers the working version of this.

What to do with the documentation you already have

Most teams reading this have a wiki with two hundred pages of varying accuracy. Do not migrate it. Decide what is essential, move that into the repository, and mark the rest as unmaintained or delete it.

An agent is useful here: give it the wiki and the codebase and ask which statements are contradicted by the current code. It will not be perfect, and it does not need to be. The output is a list to sort through, and sorting through a list is much cheaper than reading two hundred pages.

When you delete, say so on the page rather than removing it silently. A note saying this was archived on a date, and where the current answer lives, costs one line and saves the next person the twenty minutes they would spend looking for a document that used to exist. Silent deletion is how a team ends up with the same page written three times by three people who each assumed nobody had covered it.

Where this connects

Documentation is what makes conventions last, covered in keeping one codebase when everything is generated, and it is what a responder relies on in incident response for agent-written code. The handover version of the same problem, when software moves to a different owner entirely, is handing over AI-written software. The main guide puts it in context.