Architecture decision records

Short notes on decisions that are expensive to rediscover — where the reasoning matters more than the diff, and where a later reader would otherwise be within their rights to "fix" the thing on purpose.

This is not a process. Most changes need no record at all; ARCHITECTURE.md covers how the system is built and the code comments carry the local why. An ADR earns its place when the obvious thing is wrong for a non-obvious reason — usually a measured constraint the code cannot state for itself.

One file per decision, NNNN-kebab-title.md, numbered in order and never renumbered. Keep the shape:

• Status — accepted / superseded by NNNN. Records are not edited into a new opinion; a reversal is a new record that supersedes this one, because the wrong turn is usually the more useful half.
• Context — what was measured or observed. Numbers, not adjectives.
• Decision — what was done.
• Consequences — what this costs, and what it forbids. The forbidding is the point: it is what stops the decision being quietly undone.

Where the working-out lives, when it is long: docs/handoffs/. An ADR should be readable without it.