How do I document architecture decisions (ADRs)?

For every non-trivial decision, write a short Architecture Decision Record:

• Context and requirements — what problem, for whom
• At least two viable alternatives
• Constraints, risk and cost
• The chosen option and why
• Expected signals that show it is working
• Migration and rollback plan
• Owner and date

Revisit the decision when the traffic profile or the organisation changes. Review designs through eight lenses: functional, security, reliability, performance, data integrity, operations, cost and delivery (can many engineers change the system without corrupting shared work?).