Write durable Architecture Decision Records the team can find six months from now. Pick a template (MADR, Nygard, or full), list the options you considered with pros and cons, mark the chosen one, and copy the polished Markdown into /docs/adr/NNNN-slug.md. Records the why, not just the what.
An Architecture Decision Record is a short Markdown file that captures one architecturally significant decision and the reasoning behind it. The format was popularized by Michael Nygard in 2011 and refined by the MADR (Markdown Any Decision Records) project. ADRs live in your repo — typically /docs/adr/NNNN-decision-slug.md — and are sequenced, never deleted: when a decision is reversed you write a new ADR that supersedes the old one, preserving history. They are best kept short (one page), focused on a single decision, and written close to when the decision was made so the context is still fresh. Common templates: Nygard (Context / Decision / Status / Consequences), MADR (adds Decision Drivers, Options, Pros & Cons), and Y-statements for one-liners. The point isn't the format — it's that future-you (or a new engineer) can answer "why did we do it this way?" without rebuilding the whole conversation.