An opinionated but lightweight ADR practice that survives team turnover and audit review.
A 1–2 page Markdown template with the eight sections we’ve found necessary.
Lightly redacted from real projects — not synthetic.
How ADRs get drafted, reviewed, accepted, superseded.
A CLI we use internally, also included.
Plain Markdown. No tool lock-in. Edit in any editor, render anywhere.
1-page Markdown ADR template + extended version with all section guidance inline.
Real decisions: storage, tenancy, auth, queue, deploy, observability, security, billing.
Auto-generated ToC; ready to commit into your /docs/adr directory.
Optional CLI for new, supersede, index. macOS + Linux + Windows binaries.
If something isn’t answered here, ask in your intro email — we keep this list short on purpose.
You probably could. The value is in the 12 worked examples — real architecture decisions, lightly redacted, that show how the format performs under load.
Yes. Single purchase, unlimited team use. Don’t republish or resell — otherwise treat it as yours.
Yes. Lifetime updates emailed when we ship a new version. Average is one update every six months as we refine the format.
It’s plain Markdown — works in GitHub, GitLab, Notion (via paste), Confluence (via mdtoconfluence), MkDocs, Docusaurus.
We do bespoke kits, too. Send a paragraph about the problem and we’ll come back inside 48 hours.