Technical decisions fade when they're undocumented, unfindable, or made without involving the right people. The key is matching documentation weight to decision importance: verbal agreement for small reversible choices, written summaries for multi-person decisions, ADRs for architecture-limiting choices, and RFCs for high-stakes decisions needing broad input. A good ADR is a single-page document capturing context, decision, results, and rejected options. RFCs only work when they're genuine invitations for feedback with clear timelines and real follow-through. Keeping ADRs in a /docs/adr folder in the repo, using consistent numbering, and referencing them in code reviews and discussions ensures decisions remain visible and actionable rather than becoming forgotten suggestions.
Table of contents
Why Decisions Don’t StickMatch documentation to the decision’s weightADRs work because they’re simpleRFCs fail when they’re theatreInvolvement determines whether decisions stickDecisions need visible attention, not rulesKeep decisions close to the codeShared understanding, not bureaucracySort: