Architecture & Technical Design · master area

Architecture Decision Records

One constrained technical choice, with at least two options considered (including do nothing). MADR format. Signed before code lands. Never deleted; superseded.

Owner: Tech Lead Phase it lives in: What We Shape Lives in: the codebase (docs/adr/), versioned in git, numbered sequentially.

Where it lives in the chain

• What We Shape · ADR — the canon

How to do this

• Practice — Writing ADRs
• Template — ADR (MADR format)
• Checklist — ADR · ≥2 options including do-nothing
• Clinic — An ADR with one option
• Skill path — Tech Lead foundations · Step 4

Related crafts

• Ilities Selection — the trade-offs ADRs encode
• Technical Design Brief — references ADRs without embedding them
• Product Decision Records (PDR) — the product-side sibling