MADR - architecture decision records
A markdown template for recording architecture decisions: the context, the options, what was chosen, and the consequences accepted.
One file per decision, numbered, living in the repo next to the code. The value is not the decision - it is the rejected alternatives. Six months later the question is never “what did we pick”, it is “why didn’t we do the obvious thing”, and without a record you re-litigate it from scratch.
Cheap to start. One file, whenever you make a call you would have to defend later.
See also: