Documentation standards

Documentation standards

What goes where

Artefact	Contains	Read when
AGENTS.md	Only what contradicts default agent behaviour	Before writing any code
docs/decisions/	Why a thing is the way it is	Hitting a fork
docs/standards/	Rules you are held to	Onboarding, and when unsure
docs/work/	What to build, and what done means	Picking up a work item
docs/architecture.md	The narrative overview	Understanding the whole
Code comments	Non-obvious local constraints	In the file

The AGENTS.md rule

AGENTS.md is a list of things you will get wrong by default. It is not a description of the codebase.

This is the highest signal-per-token artefact in the repository and it must stay lean. Every line competes for the same limited attention, so a line that merely describes the code steals attention from a line that prevents a real failure.

Qualifies — the default is wrong here:

• “Do NOT use @neondatabase/serverless” — because it is the dominant pattern in training data for Neon on Workers, and it is wrong for this project
• “Clerk’s free tier is 50,000 MRU, not 10,000” — because the stale figure is everywhere
• “Never foreign-key to a Clerk user ID” — because it is the obvious thing to do

Does not qualify — belongs on the subsite:

• What the packages are, what a module does, how to run the dev server
• Anything an agent would get right anyway
• Anything already stated in a standard, restated for emphasis

The learning loop

When an agent gets the same platform fact wrong twice, the fix is one line in AGENTS.md — not a comment in the code.

This is step 10 of the loop. It is how the repo gets better at being worked on, and it only functions if the file stays short enough to be read every time.

Per-package AGENTS.md files are allowed where a trap is genuinely package-local.

Docs ship in the feature PR

Not a follow-up. Gate step 6 enforces it crudely — a PR touching apps/ or packages/ must touch docs/ or carry docs:n-a.

The check cannot tell good documentation from bad. It only makes forgetting impossible, which is the actual failure mode: a documentation follow-up PR is a documentation PR that never gets written.

Single sourcing

Per ADR-0013, every authored markdown file lives under docs/ at the repo root and is rendered by apps/docs through a glob loader. There is no copy step and there are no symlinks.

Consequences for authors:

• Every file needs title and description frontmatter
• Internal links are relative paths between docs/ files, so they work both on GitHub and on the subsite
• Never duplicate content between the repo and the site — the site is the repo

Writing style

• Lead with the rule; the explanation follows it.
• Prefer a table to a list of paragraphs.
• Say “must” and “never” where you mean them, and don’t where you don’t.
• Every rule that isn’t self-evident carries its reason. A rule without a reason gets worked around the first time it is inconvenient.
• Link to the ADR rather than restating its argument.