Documentation standard for agent-maintained projects

How to document a software project so the next person — or the next agent — can reconstruct not just what the code does, but why it is like that.

This describes a set of linked documents, not a single file. It applies to any project; nothing here assumes a particular language, framework or size.

The shape: a linked set, not a pile and not one long file

Documentation lives in {{docs_path}}, one file per section, with an index that links to all of them. Documents link to each other using {{link_style}}.

The structure matters for two reasons that pull the same way:

A single long document cannot be partially loaded. An agent needing the testing approach should not have to read the commercial plan to find it, and a context window spent on irrelevant sections is context not spent on the work.

An unlinked pile gets orphaned. A file nobody links to is a file nobody finds, and it rots without anyone noticing because nothing points at it to go stale. Links are what make the set navigable and what make staleness visible: a link to a feature that no longer exists is an obvious defect, while a paragraph about a feature that no longer exists is invisible.

File naming

Fixed, so that links are predictable and an agent arriving in an unfamiliar project can guess the path before looking.

{{docs_path}}README.md            index — links to everything below
{{docs_path}}about.md
{{docs_path}}architecture.md
{{docs_path}}licensing.md
{{docs_path}}features.md
{{docs_path}}decisions.md
{{docs_path}}test-strategy.md
{{docs_path}}security.md
{{docs_path}}runbook.md             for anything deployed or shipped
{{docs_path}}roadmap.md
{{docs_path}}commercialisation.md   optional

{{docs_path}}user-guide.md          user documentation, if the project has users
  OR
{{docs_path}}user/                  the same, as chapters, with a README.md index

Some files belong at the repository root, not in the set, because tooling and convention expect them there: README.md, LICENSE, SECURITY.md, CHANGELOG.md, and whatever instruction file your agent reads. Code hosts treat several of these specially, and moving them costs behaviour you want.

The root README.md and {{docs_path}}about.md overlap enough that both get written and one rots. Give them different jobs: the root README orients someone who has just arrived at the repository — what this is, how to run it, where the documentation is — and about.md explains what the software does for the person using it, at length and without jargon. If the README grows past a screen, the surplus belongs in the set.

The rules behind those names:

• Lowercase, hyphen-separated, .md. Case sensitivity differs between operating systems and hosts, so a link that works on one machine can fail on another; lowercase removes the question entirely.
• No spaces. They require escaping in relative links and are a persistent source of broken references.
• No numeric prefixes on sections. They encode an order that changes, and the index already provides order.
• README.md is the single uppercase exception, because code hosts render it automatically when someone browses the directory. That behaviour is worth more than the consistency it costs.

Consistency matters more than the specific scheme. Most tools are flexible; what breaks is a project where two conventions coexist and links guess wrongly between them. Pick these names, or pick others and apply them everywhere.

When a section outgrows one file, promote it to a directory with the same name and a README.md index inside: {{docs_path}}features/, {{docs_path}}decisions/. Features and the Decision Log are the two that normally get there first. Decision entries are the one place a numeric prefix earns its keep — decisions/0007-use-server-side-rendering.md — because there the number is a stable identifier to link to, not a sort order.

The set records when it was last confirmed

The three writing rules below all depend on currency — update in the same change, date anything version-dependent, delete what has stopped being true — and none of them can be checked without a reference point. Nobody can tell a current architecture.md from one that stopped being true in March.

So {{docs_path}}README.md names the commit the set was last confirmed against, and any file that rots faster than the rest carries its own line:

Last confirmed against: a1b2c3d (2026-08-25)

That single line is what converts an instruction into something that holds. It makes staleness detectable without anyone judging the prose: read the commit, diff it against the current head, and report that the architecture was confirmed at a point since which forty files have changed. No opinion about quality, no word count — just a fact that goes out of date visibly.

It also guards the set against its own most likely failure. Documentation does not usually fail by being absent. It fails by being present and wrong, which is worse, and which nothing else here can detect.

The sections

Each is its own file. Omit one only when it genuinely does not apply — an empty section is more honest than a missing one, because it tells the reader the question was asked.

What each contains is mostly obvious from its name and is not restated here. What is not obvious is why these particular sections, and the three notes below.

• About — plain English, for the one reader who is not technical. No architecture, no justification.
• Architecture — the map, not the territory. Write the diagram as text (Mermaid or similar) rather than embedding an image: a text diagram diffs, survives being edited by an agent, and cannot silently disagree with the prose after a refactor. An exported image does all three badly.
• IP Rights and Licensing — every third-party component, its licence, and any obligation it places on the project. This is the section everyone skips and then needs urgently, usually the week somebody asks whether the project can be sold, open-sourced or shipped to a client. Reconstructing it later means auditing a dependency tree under time pressure; maintaining it costs a line per dependency.
• Features — one entry per component, linked from Architecture.
• Testing, Runbook, Decisions — see the runbook and decisions rootnotes for what belongs in the last two.

What to read first

A set exists partly so that an agent can load part of it. Say which part.

For a change to one feature: about.md, then that feature’s entry, then the decisions it links to. Skip the rest — a context window spent on the commercial plan is context not spent on the change.

For a change touching how components fit together, start at architecture.md instead. For anything operational, runbook.md on its own is usually enough.

The index should say this, so nobody has to work it out from the file list.

The links are the structure

Four relationships carry the set. Get these right and it stays navigable:

• Architecture → Features. Each component named in the map links to its detailed entry.
• Features ↔ Decision Log. Every non-obvious feature links to the decisions that shaped it, and each decision links back.
• Features ↔ Test Strategy. Every feature links to how it is verified, and every testing approach names what it covers.
• Roadmap → Features. On completion, the item moves.

A document that links to nothing and is linked from nothing is the warning sign.

Writing rules

Do not narrate the code. An agent asked to “document this” will by default describe what the code does — the least valuable documentation and the fastest to rot, adding nothing while it is correct because the code was already there. Document what the code cannot say: why this approach, what was rejected, what breaks if it changes, what looks incidental but is load-bearing, which constraints are external and not yours to simplify away.

A useful test: if a rename would invalidate the sentence, it is describing mechanics, and mechanics belong in the code.

Update documentation in the same change as the code it describes. A follow-up commit is a commit that does not happen.

Date anything version-dependent, and say what it was true of. An undated technical claim cannot be assessed later.

Delete what has stopped being true. A deleted document is honest; a stale one misleads, and misleads an agent more efficiently than a human, because the agent has no instinct that something reads oddly.

No screenshots of code or terminal output. They cannot be searched, copied, diffed or read aloud, and they go stale invisibly.

Spelling: {{spelling_variant}}, matching whatever the product’s user-facing copy uses. Documentation that spells things differently from the interface it describes makes both look unmaintained, and it breaks search for anyone looking up a term they read on screen.

What is deliberately not here

A changelog. This set documents what exists and what is planned; a changelog records what shipped. That is a release artefact, tied to versions and tags, and it lives at the repository root. The Decision Log already answers the question a changelog usually gets reached for — why is it like this — and answers it better.

The absence is a decision rather than an oversight, which is why it is written down.

User documentation

Everything above documents the project for whoever maintains it. Documentation for people using the software is a different thing with a different organising principle, and merging them serves neither.

Two shapes, chosen per project rather than by rule:

• {{docs_path}}user-guide.md — one document, when the whole guide can be read or scanned in a pass.
• {{docs_path}}user/ — chapters with a README.md index, when there are task areas a reader navigates between.

The question is whether a reader arrives wanting the whole thing or one part of it. Start with the single file; split it when a reader would scroll past two irrelevant sections to reach theirs.

Write the uninstall, export and recovery paths. They are what people search for under pressure and they are almost always missing — which is the one rule here that does not get followed by default.

Link the user documentation from the index, and from any Features entry where the technical and user-facing descriptions should stay in step.

Related rootnotes

This set has two companions, and the boundary between them is worth stating so an agent reading one does not invent what the others say.

• The working agreement governs how changes are made — what may be run unattended, what stops for a human, and what an honest report of the work looks like. This document governs what gets written down; that one governs how the writing gets committed.
• The operational rootnote sets out what runbook.md must contain and how to behave when something is actually broken. This document names the file; that one fills it.

For the agent working here

• Put every document in a section this standard names. A well-written file in a location nobody expects is not a contribution.
• Add the links. A new feature entry that links to nothing has done half the job.
• Do not write documentation instead of doing the work. A thorough document about an unfinished feature is worse than a note saying it is unfinished.
• Do not silently rewrite an existing document. Show what changed, particularly when removing something — the removed line may be the only surviving record of a constraint.
• When unsure whether something merits documenting, write the decision entry. It is short, it is the highest-value form, and it is the one nobody regrets.