Skip to content
Shannon

Architecture Decision Records

An Architecture Decision Record (ADR) captures a single significant technical decision — the context, the options considered, the choice, and the consequences — so that future readers can reconstruct why without having to excavate git history or interrupt the people who were there.

Shannon’s ADRs cover cross-cutting decisions. System-specific decisions (e.g. “why we chose a particular Salesforce flow pattern”) live in the system’s own source repo.

Format

Section titled “Format”

All Shannon ADRs follow MADR — Markdown Architecture Decision Records. Each ADR has:

  1. Context and problem statement — the forcing function, the constraints, what we’re optimising for.
  2. Decision drivers — the axes that mattered for the choice.
  3. Considered options — genuine alternatives, not straw men.
  4. Decision outcome — which option, and why.
  5. Consequences — what we accept (positive and negative) as a result.

Rules

Section titled “Rules”
  • Numbered sequentially, zero-padded to four digits (0001, 0002, …). Never reuse a number, even if an ADR is withdrawn.
  • Append-only. To change a decision, write a new ADR that supersedes the old. Mark the old status: deprecated and add a Superseded by link at the top.
  • One decision per ADR. Don’t bundle.
  • Short. An ADR is not an essay. If it won’t fit on two printed pages, you’re doing too much.

Index

Section titled “Index”

The sidebar enumerates every ADR in this directory. See the list on the left, or use the site search for a keyword.