ADR (Architecture Decision Record)
Ett kort dokument som beskriver ett viktigt tekniskt beslut: vad som beslutades, varför och vad det får för följder.
- Kategori
- Utvecklingsflöde
ADR, ADR, ADR:er, arkitekturbeslut, beslutsdokument
Enkel förklaring
I varje projekt fattas beslut som påverkar mycket: vilka verktyg som används, hur saker ska fungera och vad man avstår från. Ett halvår senare minns ingen varför.
En ADR är ett kort dokument för ett sådant beslut. Det beskriver situationen, beslutet och följderna, så att den som kommer efter kan förstå varför projektet ser ut som det gör.
Arkitektur betyder här hur ett system är uppbyggt i stort.
Teknisk förklaring
Formatet beskrevs av Michael Nygard 2011. En ADR har vanligtvis:
- ett nummer och en rubrik
- en status, till exempel föreslagen, godkänd eller ersatt
- sammanhang: läget och vad som påverkar beslutet
- beslut: vad som har beslutats
- konsekvenser: vad som följer av beslutet, både bra och dåligt
ADR:er ligger som textfiler i repot och granskas i pull requests, precis som koden. Ändras ett beslut skrivs en ny ADR, och den gamla markeras som ersatt men finns kvar.
Praktiskt exempel
Kodkollektivet Academy har nio ADR:er. Några exempel:
- varför webbplatsen inte har någon server-del eller inloggning
- varför uppgifterna om varje kurs ligger i en egen fil, skild från texterna
- vilka krav som gäller för de programpaket som projektet använder
Varje ADR anger datum och vem som beslutade. Bryter en ny ändring mot ett beslut syns det i granskningen, och då skrivs en ny ADR i stället för att det gamla beslutet glöms bort.
När och varför används det?
En ADR skrivs när ett beslut är svårt att ändra, påverkar många delar eller när det fanns flera rimliga alternativ. Den hjälper nya medlemmar att förstå projektet och gör det lättare att ompröva ett beslut med rätt underlag.
ADR:er är också användbara när en AI-agent arbetar i projektet: dokumenten förklarar varför koden ser ut som den gör.
Rekommendation: håll varje ADR kort, en till två sidor, och skriv den när beslutet fattas, inte i efterhand.
Vanliga missförstånd
- “Ett gammalt beslut skrivs om när det ändras.” Nej. Den gamla ADR:en finns kvar som historik, och en ny ersätter den.
- “ADR:er är bara för stora organisationer.” Nej. De är lika användbara i ett litet projekt, och tar bara några minuter att skriva.
- “En ADR är en fullständig specifikation.” Nej. Den beskriver ett enda beslut och varför det fattades.