Documentation Standard

Code says what the system does; documentation says how to run it, why it is built this way, and where it is going. This standard defines the documents every repository keeps, when design docs and Architecture Decision Records (ADRs) are required, and how both are kept current.

The documentation harness

The template installs these files. make docs-check (part of the required standards check) fails when any of them is missing, except evals/, which is required only for LLM / RAG features and is not checked automatically. Missing README required sections are a warning, because repositories adopting the template keep their own README.

File	Purpose	Update when
README.md	Overview, ownership, getting started (required sections)	Purpose or ownership changes
CHANGELOG.md	Release notes - Added / Changed / Fixed / Security	Every user-visible change, in the same PR
docs/ARCHITECTURE.md	How the system is built: components, data, integrations, observability	Structure, data, or integrations change
docs/adr/NNNN-title.md	Why - one decision per file	A significant technical decision is made
docs/RUNNING.md	From a fresh clone to a running system	Setup or run commands change
docs/TESTING.md	Test layers, commands, and rules	The test approach changes
docs/DEPLOYMENT.md	Environments, release steps, rollback	Pipelines or environments change
docs/ROADMAP.md	Direction - now, next, later	A goal starts, ships, or is dropped
docs/RELEASES.md	The release record: release log + environments view	Every promotion to production
AGENTS.md	Rules for engineers and AI assistants, and the project's conventions record	A convention changes
evals/	The frozen task set for LLM / RAG features	Behavior expands or a new failure mode is found
SECURITY.md	How to report a vulnerability	Contacts change

Docs change in the same PR as the code they describe. A PR that changes setup without updating docs/RUNNING.md is incomplete, and reviewers treat it that way (see the Code Review Standard).

Architecture Decision Records

An ADR records one significant decision: the context, the decision, the alternatives, and the consequences. Write one when a change:

• adds or replaces a framework, database, queue, or other major dependency;
• changes how services communicate, or the boundaries between them;
• changes the data model in a way that is hard to reverse;
• changes infrastructure, deployment, or the security model;
• will make a future engineer ask "why on earth did they do it this way?".

Rules:

• Numbered and immutable: docs/adr/0007-use-postgres-for-events.md. A changed decision gets a new ADR that supersedes the old one; the old one is marked superseded, not edited.
• Added before or with the change it justifies, and reviewed in that PR.
• Short - one or two pages. Use docs/adr/0000-template.md.

The standards check warns when architecture-sensitive paths (infrastructure, migrations, dependency manifests, workflows) change without an ADR or an ARCHITECTURE.md update.

Design docs

A design doc comes before the code for work that is large, risky, or hard to reverse - as a guide, work expected to take more than about a week, or anything crossing team or client boundaries. It covers:

1. Problem and goals - including explicit non-goals.
2. Proposed design - with a diagram where it helps.
3. Alternatives considered and why they lost.
4. Risks - security, personal data, cost, operability, rollback.
5. Rollout plan - how it ships and how it is verified.

The design doc is reviewed by the Tech Lead (and the client where relevant) before implementation starts. The decisions it settles become ADRs.

Write for the next engineer

The reader of your docs was not in the room. If they need tribal knowledge to use a doc, the doc is not done.