Decisions#
An architecture decision record (ADR) states what was decided, what was rejected, and why. It helps future contributors tell a deliberate constraint from an old habit.
When to write one#
Write an ADR when a decision:
changes the trust or security model, however narrowly (ADR 3, ADR 4);
fixes a contract other code will accumulate around (ADR 2);
rejects an obvious alternative for a reason that will not be obvious later.
Do not write one for a decision a test already states, or one that is cheap to
reverse. An ADR that records "we named the function parse" teaches nobody
anything.
How#
Copy the shape of an existing record: Status, Date, Context, Decision, Consequences (positive, negative, follow-up), Alternatives considered.
Number it after the last one and name the file
NNNN-short-kebab-title.md.Land it in the same pull request as the change it explains, so the decision and its implementation are reviewed together.
Do not delete or rewrite a superseded ADR. Change its status to
Superseded by ADR N, and state what changed in the new record.
Index#
| ADR | Decision |
|---|---|
| 1 | Node 24+, ESM only, TypeScript builds to dist/ |
| 2 | documents are staged immutable values with branded path types |
| 3 | one hash-pinned script for live reload, development only |
| 4 | the page client (search, copy) ships on every page, by hash |
| 5 | no configuration file; composition is code, conventions are documented |
| 6 | .mdx is a source format; its expressions, components and imports never execute |
| 7 | --trust lets the operator opt in to executing the root's scripts and MDX |
| 8 | explicit locale directories form isolated content scopes |
| 9 | Tsumugu draws a Mermaid subset itself, at build time, with no dependency |
| 10 | OpenAPI descriptions are documents, claimed by file name |
tests/decisions.test.ts checks that every record in this directory appears in
the index and that every index entry resolves to a file.