Architecture decision records
A decision record says what was decided, when, against what alternatives, and what it costs. It is historical by construction: it carries a date, and it is never rewritten to match today. When a decision is reversed, a new record supersedes the old one and says so; the old one stays.
Why this directory exists
The comments in this repository explain a great deal, and that is what makes them worth reading: “we had found that…”, “at the start there were fifteen modules…”. The reasoning carries across; the number goes stale. Three docstrings still said “575 tests” when there were six hundred and thirteen; another said “46 modules” when the collection publishes fifty. None was wrong the day it was written.
So the rule, and mise run histoire is its executable form:
A number counting things in this repository does not belong in a sentence. If it is true, something must go red when it changes: an assertion, a golden, a derived block. If it is history, it belongs in a decision record, which carries its date.
Code says the current invariant. This directory says what happened.
The records
record |
decision |
|---|---|
No operation disappears; what no rule settles is |
|
Terraform provisions, Ansible operates: no create, no delete, no wiring |
|
A managing module reads the resource, computes the difference, and writes only that |
|
|
|
Generated documentation is refused, not merely reported, when it is unusable |
|
The local emulator proves the shape of a run, never the real cloud |
|
A measured number is derived, an assertion, or dated history, never a sentence |
|
A contract constraint is translated, or counted, or measured absent, never guessed |
|
The type decides the comparison it can, an override decides the rest, nothing is guessed |
|
After writing, what was asked is compared with what is observed, and a gap fails the module |
|
A product passes a gate before entering the index, and enters with its price known |
|
An explicit |
|
When a module, option or return appeared is read from a journal, never from the current version |
|
The runtime composes its own HTTP request, and no private attribute of a third-party library is shipped |
|
A claim about the real API is a recorded exchange, not a green assertion |
|
A clearable field is cleared with the empty value of its type, and an explicit |
|
On a failed destruction the launcher removes what blocks it, once, only within the run’s own platform, and says what it removed |
|
A retry policy belongs to the operation: a read replays, a write only when the server says it did nothing, an action never |
|
An API name filter narrows a listing, it never selects: the exact comparison is local, and two matches refuse |
|
A plan describes the fleet as it was read, and is never replayed: the execution reads again |