ADR Authoring Guide

Help users write Architectural Decision Records that future developers actually read and that automated review systems can enforce. Based on Michael Nygard's format from Documenting Architecture Decisions.

How to Think About ADRs

An ADR captures a decision at a moment in time. It answers: what did we decide, why, and what happens because of it? The audience is a future developer (or an AI reviewer) who encounters code that seems odd and needs to understand the reasoning behind it.

The Decision section is the heart of an ADR — it's what gets enforced. The rest (Context, Consequences) provides the reasoning that makes enforcement feel reasonable rather than arbitrary. Spend most of your effort on the Decision section, and write it at the enforceability level the team actually needs.

Workflow