Overview
- Martin Fowler outlines ADRs as brief, single‑decision documents with explicit status that move from proposed to accepted and later to superseded through linked replacements.
- He recommends storing records in the code repository under doc/adr, writing them in Markdown, and numbering files in order with descriptive names for easy scanning.
- Each record should state the problem, key trade‑offs, real alternatives with pros and cons, likely consequences, and a confidence level or review triggers in an inverted‑pyramid style.
- Fowler says writing ADRs improves team thinking and supports the Advice Process by drawing out expertise and recording a concise summary of the advice taken.
- A counterpoint from a developer argues append‑only ADR folders become clutter and proposes a curated 100‑line DESIGN.md for current decisions, rich code comments for local context, and git history as the audit trail.