Et ADR, architecture decision record, er et kort notat om én teknisk beslutning: hvad blev besluttet, hvorfor, og hvad blev fravalgt. Et notat fylder højst en side, tager en halv time at skrive og kan læses af den, der kommer om tre år. Værdien viser sig, når den person, der traf valget, er rejst, og nogen spørger, om det gamle valg stadig gælder. Uden notatet gætter teamet, og så bliver en gammel beslutning enten forsvaret i blinde eller væltet, uden at nogen ved, hvad den beskyttede.
Hvad notatet løser
Af koden fremgår det, hvad produktet gør. Begrundelsen for opbygningen og de afviste muligheder står der sjældent. Den viden bor hos de mennesker, der var med. Når de skifter job, forsvinder begrundelsen, og tilbage står et mærkeligt valg, som en ny udvikler med god grund vil lave om.
Tre situationer gør det særlig synligt. En ny CTO eller lead developer skal sætte sig ind i produktet. En afgående teknisk leder skal overdrage, se opsigelsesperioden for en CTO. Eller en stor kunde beder om en begrundelse for, hvorfor produktet er bygget, som det er.
Hvad der skal skrives ned
Skriv de beslutninger ned, der er svære at ændre eller berører flere end én udvikler. Det dækker især de arkitekturvalg, der koster mest at fortryde: datamodellen, opdelingen mellem kunder, login og integrationer. Dertil kommer valg af platform og hosting, større købte komponenter og bevidste genveje, hvor I ved, at regningen kommer senere.
Valg af navne, små biblioteker og kodestil hører ikke hjemme her. En tommelfingerregel: Ville en ny kollega om to år spørge “hvorfor i alverden gjorde I sådan?”, så skriv et notat.
Skabelonen
Seks felter er nok. Hold teksten så kort, at nogen faktisk gider læse den.
- Titel og dato. En hel sætning, der siger beslutningen: “Vi bruger én fælles database med kunde-id på alle tabeller.” Nummerér notaterne fortløbende.
- Status. Foreslået, besluttet eller afløst af notat nummer det og det.
- Baggrund. Hvad var situationen? Hvor mange kunder, hvor stort et team, hvilke krav og hvilken tidsfrist? Det er dette felt, der fortæller en senere læser, om forudsætningerne stadig gælder.
- Beslutning. Hvad vi gør, skrevet i nutid og uden forbehold.
- Fravalg. De muligheder, der blev overvejet, og den korte grund til, at de blev valgt fra.
- Konsekvenser. Hvad bliver lettere, hvad bliver sværere, og hvad skal vi holde øje med? Hvornår bør beslutningen tages op igen?
Et tænkt eksempel på det sidste felt: “Fælles database gør opdateringer enkle. Eksport af én kunde bliver mere besværlig. Tages op igen, hvis en kunde kræver egen installation.”
Hvor notaterne skal ligge
Læg dem i samme repository som koden, altså det arkiv, hvor udviklerne alligevel arbejder, som almindelige tekstfiler i en fast mappe. Så følger de med ved en overdragelse og kan gennemgås på samme måde som kode. Et dokument på et fællesdrev eller en side i et projektværktøj går let tabt ved første skift af værktøj.
Læseadgang for ledelsen er en god idé, men ingen bør forvente, at direktøren følger med i mappen. Bed i stedet om en kort liste over nye notater i den faste status, se teknologien på ledelsesmødet.
Sådan holder I vanen
Den svære del er at få skrevet notatet, mens beslutningen er frisk. Tre små regler hjælper:
- Den, der foreslår en ændring, skriver notatet, og teamet diskuterer ud fra teksten. Så bliver notatet en del af beslutningen.
- Gamle notater rettes ikke. Ændrer I mening, skriver I et nyt og markerer det gamle som afløst. Historien er pointen.
- Nyt arbejde, der rører et af de dyre valg, skal pege på et notat, før det godkendes.
Begynd med de ti vigtigste eksisterende beslutninger. Bed den, der kender produktet bedst, om at skrive dem ned bagud med ærlige huller, hvor begrundelsen er glemt. Det tager få timer og er en af de billigste forsikringer mod nøglepersonafhængighed, I kan tegne.
Notaterne har andre læsere
Beslutningsnotaterne er råstof til meget andet. Den arkitekturbeskrivelse, en kunde beder om, bliver hurtigere at skrive, og en teknisk køreplan kan pege på de beslutninger, der skal tages op igen.
Udvikler I noget, hvor udfaldet er usikkert, kan notaterne også indgå i det materiale, der viser, hvad I forsøgte. Spørgsmålet om dokumentation over for skat og tilskud er beskrevet i dokumentation af udviklingsprojekter. Formatet er det samme, og fravalgene og de usikre punkter bliver mere værd, når de er skrevet ned undervejs.
Det skal I lade være med
- At gøre notatet til et langt dokument · så bliver det ikke skrevet, og de vigtige valg står lige så udokumenterede som før.
- At skrive beslutningen uden fravalg · fravalgene er dem, der sparer teamet for at føre samme diskussion igen.
- At lade ét menneske eje alle notater · så flytter I nøglepersonrisikoen til dokumentationen.
Det skal I kræve af den eksterne
- ☐ Skriftlige notater for de dyre beslutninger, i teamets eget arkiv.
- ☐ Begrundelser skrevet, så direktøren kan følge dem.
- ☐ En fast skabelon, som teamet bruger selv, når den eksterne ikke er der.
- ☐ En liste over beslutninger, der bør tages op igen, med en dato eller en anledning.
Senest gennemgået: november 2026.
Næste skridt
Læs også: Arkitekturbeskrivelsen på tre sider · Når én udvikler kender hele koden
→ Kontakt · Tlf. 70 13 63 23 · Ekstern CTO hos Nielco IT
