Leader: ADR process
This course covers Architecture Decision Records (ADRs), using one Rails repository as the running example. It starts with decisions that live only in a rules document or in git history, with no reasoning attached. It then defines an ADR: short, immutable, numbered, about one decision and written at the time. The lessons show how to write a full ADR, choose which decisions deserve one, supersede instead of editing, and link ADRs to the rules document. The final lesson writes one ADR in thirty minutes.
What you'll learn
- ✓Why a rules document and git history do not record decisions
- ✓The ADR format: context, decision, consequences and alternatives
- ✓Writing the consequence you dislike and naming the expiry condition
- ✓Filtering which decisions deserve an ADR
- ✓Superseding an accepted ADR without editing it
- ✓Linking ADRs and the rules document in both directions
The decisions with no record
This repository has two documents that look like they record decisions, and neither one does.
Read the full lesson free →Curriculum
7 lessonsThe decisions with no record
Shows how MEMORY.md and git history each miss the reasoning behind four decisions in this application.
What an ADR is
Defines an ADR as short, immutable, numbered and about one decision, with its format and status lifecycle.
Writing one
Writes the full ADR for running student code in the browser and explains what each section records.
What to record
Applies one filter, whether someone would have to re-derive it, to choose which decisions deserve an ADR.
Superseding, never editing
Explains why a changed decision gets a new superseding ADR while the old record stays unedited.
ADRs and the rules document
Separates the present-tense rules document from past-tense ADRs and shows how to link the two.
Putting it together: thirty minutes
Writes the Pagy ADR in thirty minutes, reviews the habits, and uses citation as the measure.