Architecture Decision Record

Arkitekturbeslutningslogg (ADR)

Maler, eksempler og veiledning for å dokumentere arkitekturbeslutninger.

En arkitekturbeslutningslogg (ADR) er et dokument som fanger opp en viktig arkitekturbeslutning som er tatt, sammen med konteksten og konsekvensene av den.

Oversettelser: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, Lietuvių, Gaeilge, Lëtzebuergesch, తెలుగు, தமிழ், मराठी, Hausa, ગુજરાતી, Euskara, भोजपुरी, Basa Jawa, فارسی, ਪੰਜਾਬੀ, Malti, Latviešu, Slovenščina, Slovenčina, Hrvatski, Български, Čeština, Magyar, Ελληνικά, Română, Polski, Español, Eesti, Suomi, Français, हिन्दी, Bahasa Indonesia, Íslenska, Italiano, 日本語, 한국어, Nederlands, Português, Русский, Svenska, Kiswahili, ไทย, Türkçe, اردو, Tiếng Việt, 中文

Gjør din egen grundige vurdering av disse ressursene før du bruker dem i kritiske systemer.

Innhold:

Maler:

Eksempler:

Hva er en arkitekturbeslutningslogg?

En arkitekturbeslutningslogg (architecture decision record, ADR) er et dokument som fanger opp en viktig arkitekturbeslutning som er tatt, sammen med konteksten og konsekvensene av den.

En arkitekturbeslutning (architecture decision, AD) er et valg i programvaredesign som svarer på et vesentlig krav.

En samling av arkitekturbeslutninger (architecture decision log, ADL) er alle ADR-er som er opprettet og vedlikeholdt for et bestemt prosjekt (eller en bestemt organisasjon).

Et arkitektonisk betydningsfullt krav (architecturally-significant requirement, ASR) er et krav som har en målbar innvirkning på arkitekturen til et programvaresystem.

Alt dette hører inn under temaet forvaltning av arkitekturkunnskap (architecture knowledge management, AKM).

Målet med dette dokumentet er å gi en rask oversikt over ADR-er, hvordan du lager dem og hvor du finner mer informasjon.

Forkortelser:

  • AD: arkitekturbeslutning

  • ADL: samling av arkitekturbeslutninger

  • ADR: arkitekturbeslutningslogg

  • AKM: forvaltning av arkitekturkunnskap

  • ASR: arkitektonisk betydningsfullt krav

Slik kommer du i gang med ADR-er

For å komme i gang med ADR-er bør du snakke med teamkollegene dine om disse områdene.

Identifisering av beslutninger:

  • Hvor haster og hvor viktig er AD-en?

  • Må den tas nå, eller kan den vente til man vet mer?

  • Både personlig og felles erfaring, i tillegg til anerkjente designmetoder og praksiser, kan hjelpe med å identifisere beslutninger.

  • Ideelt sett bør du føre en beslutningsliste som utfyller produktets oppgaveliste.

Beslutningstaking:

  • Det finnes mange teknikker for beslutningstaking, både generelle og spesifikke for programvarearkitektur, for eksempel dialogkartlegging.

  • Gruppebeslutninger er et aktivt forskningsemne.

Iverksetting og håndheving av beslutninger:

  • AD-er brukes i programvaredesign. Derfor må de formidles til og godtas av interessentene i systemet som finansierer, utvikler og driver det.

  • Arkitektonisk tydelige kodestiler og kodegjennomganger som fokuserer på arkitektoniske hensyn og beslutninger er to beslektede praksiser.

  • AD-er må også vurderes (på nytt) når et programvaresystem moderniseres i løpet av programvareevolusjonen.

Deling av beslutninger (valgfritt):

  • Mange AD-er går igjen på tvers av prosjekter.

  • Erfaringer med tidligere beslutninger, både gode og dårlige, kan derfor være verdifulle gjenbrukbare ressurser når man bruker en eksplisitt strategi for kunnskapsforvaltning.

Dokumentasjon av beslutninger:

  • Det finnes mange maler og verktøy for å fange opp beslutninger.

  • Se smidige miljøer, for eksempel ADR-ene til M. Nygard.

  • Se tradisjonell programvareutvikling og prosesser for arkitekturdesign, for eksempel tabelloppsettene som IBM UMF og Tyree og Akerman fra CapitalOne foreslår.

Mer informasjon:

Slik kommer du i gang med ADR-er og verktøy

  • MySpec — Automatisert plattform for spesifikasjoner og arkitekturbeslutninger som strukturerer prosjektets grunnlov, den tekniske arkitekturen og ADR-er i ryddig Markdown, tilgjengelig via MCP.

Du kan komme i gang med ADR-er og verktøy på den måten du selv ønsker.

For eksempel:

  • Hvis du liker Google Disk og redigering på nett, kan du lage et Google-dokument eller et Google-regneark.

  • Hvis du liker å bruke versjonskontroll av kildekode, for eksempel git, kan du lage én fil per ADR.

  • Hvis du liker prosjektplanleggingsverktøy, for eksempel Atlassian Jira, kan du bruke verktøyets planleggingsoversikt.

  • Hvis du liker wikier, for eksempel MediaWiki, kan du lage en ADR-wiki.

Slik kommer du i gang med ADR-er og git

Hvis du liker å bruke versjonskontroll med git, viser vi her hvordan vi liker å komme i gang med ADR-er og git i et typisk programvareprosjekt med kildekode.

Lag en katalog for ADR-filer:

$ mkdir adr

Lag en tekstfil for hver ADR, for eksempel choose-database.md:

$ vi choose-database.md

Skriv hva du vil i ADR-en. Se malene i dette arkivet for ideer.

Commit ADR-en til git-arkivet ditt.

Claude Code-ferdigheter for ADR-er

Dette arkivet inneholder to Claude Code-ferdigheter (skills) under skills/, slik at en KI-kodeagent kan skrive og vedlikeholde ADR-er på den måten dette prosjektet anbefaler:

  • architecture-decision-record-skill — til generell bruk, for alle som skriver en ADR i et hvilket som helst prosjekt. Hjelper med å avgjøre om en beslutning trenger en ADR, oppretter en katalog adr/ eller decisions/, gir filen navn, velger en mal blant de elleve medfølgende skjelettene og skriver solide deler om kontekst, beslutning og konsekvenser.

  • architecture-decision-record-maintainer-skill — særlig for dem som vedlikeholder dette arkivet. Dokumenterer oppbyggingen av arkivet, konvensjonen om å speile README og locales og de nøyaktige trinnene for å legge til en ny mal, et nytt eksempel eller en ny verktøylenke.

For å bruke en ferdighet kopierer du mappen dens til .claude/skills/ i roten av arkivet du arbeider i (eller til ~/.claude/skills/ for å gjøre den tilgjengelig i alle prosjekter), og ber deretter Claude Code skrive eller gjennomgå en ADR.

Filnavnkonvensjoner for ADR-er

Hvis du velger å lage ADR-ene dine som vanlige tekstfiler, kan du ønske å finne på en egen filnavnkonvensjon for ADR-er.

Vi foretrekker en filnavnkonvensjon med et bestemt format.

Eksempler:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Vår filnavnkonvensjon:

  • Navnet er en verbfrase i presens imperativ. Det gjør det lettere å lese og passer til formatet vi bruker i commit-meldinger.

  • Navnet bruker små bokstaver og bindestreker (som dette arkivet). Det er en balanse mellom lesbarhet og bruksvennlighet i systemet.

  • Filtypen er markdown. Det kan være nyttig for enkel formatering.

Tips for å skrive gode ADR-er

Kjennetegn på en god ADR:

  • Begrunnelse: Forklar grunnene til at den aktuelle AD-en tas. Det kan omfatte konteksten (se nedenfor), fordeler og ulemper ved ulike mulige valg, sammenligning av funksjoner, diskusjoner om kostnad og nytte, og mer.

  • Avgrenset: Hver ADR skal handle om én AD, ikke flere.

  • Tidsstempler: Angi når hvert punkt i ADR-en er skrevet. Dette er særlig viktig for forhold som kan endre seg over tid, som kostnader, tidsplaner, skalering og lignende.

  • Uforanderlig: Ikke endre eksisterende informasjon i en ADR. Utvid i stedet ADR-en med ny informasjon, eller erstatt ADR-en ved å lage en ny ADR.

Kjennetegn på en god «Kontekst»-del i en ADR:

  • Forklar organisasjonens situasjon og forretningsmessige prioriteringer.

  • Ta med begrunnelser og hensyn som bygger på teamenes sosiale sammensetning og kompetanse.

  • Ta med fordeler og ulemper som er relevante, og beskriv dem på måter som stemmer med dine behov og mål.

Kjennetegn på en god «Konsekvenser»-del i en ADR:

  • Forklar hva som følger av å ta beslutningen. Det kan omfatte virkninger, utfall, resultater, oppfølging og mer.

  • Ta med informasjon om eventuelle etterfølgende ADR-er. Det er ganske vanlig at én ADR utløser behov for flere ADR-er, for eksempel når én ADR gjør et stort overordnet valg som igjen skaper behov for flere mindre beslutninger.

  • Ta med eventuelle prosesser for gjennomgang i etterkant. Det er vanlig at team gjennomgår hver ADR en måned senere, for å sammenligne informasjonen i ADR-en med det som faktisk har skjedd i praksis, slik at de kan lære og utvikle seg.

En ny ADR kan erstatte en tidligere ADR:

  • Når det tas en AD som erstatter eller opphever en tidligere ADR, bør det lages en ny ADR

Eksempelmaler for ADR-er

Eksempelmaler for ADR-er som vi har samlet på nettet:

Råd om teamarbeid for ADR-er

Hvis du vurderer å bruke beslutningslogger sammen med teamet ditt, får du her noen råd vi har lært av å arbeide med mange team.

Du har en mulighet til å gå foran som leder for teamkollegene dine ved å snakke sammen om «hvorfor» i stedet for å pålegge «hva». Beslutningslogger er for eksempel en måte for team å tenke smartere og kommunisere bedre på. De er ikke verdifulle hvis de bare er et krav om papirarbeid som tvinges inn i etterkant.

Noen team foretrekker navnet «beslutninger» framfor forkortelsen «ADR-er». Når noen team bruker katalognavnet «decisions», er det som om en lyspære tennes, og teamet begynner å legge mer informasjon i katalogen, for eksempel leverandørbeslutninger, planleggingsbeslutninger, tidsplanbeslutninger og så videre. Alle disse typene informasjon kan bruke samme mal. Vi antar at folk lærer raskere med ord («beslutninger») enn med forkortelser («ADR-er»), at folk blir mer motivert til å skrive dokumenter underveis når ordet «logg» fjernes, og at noen utviklere og noen ledere ikke liker ordet «arkitektur».

I teorien er uforanderlighet ideelt. I praksis har foranderlighet fungert bedre for teamene våre. Vi setter inn ny informasjon i den eksisterende ADR-en, med dato og en merknad om at informasjonen kom etter beslutningen. Denne tilnærmingen gir et «levende dokument» som vi alle kan oppdatere. Typiske oppdateringer kommer når vi får informasjon takket være nye teamkolleger eller nye tilbud, eller fra resultater av egen bruk i praksis, eller fra endringer hos tredjeparter i etterkant, for eksempel leverandørers funksjoner, prisplaner, lisensavtaler og så videre.

Spørsmål om teamarbeid for ADR-er

Hvem kan lage en ADR?

Tenk på områder som bestemte personer, bestemte roller, bestemte team eller bestemte avdelinger. Vurder også om det finnes personer, roller, team eller avdelinger som kan bestille en ADR, det vil si be om en som noen andre skal skrive.

Eksempelsvar: Alle i organisasjonen vår som har lest README-siden om arkitekturbeslutningslogger, kan foreslå en ADR, det vil si at personen kan begynne å skrive den og dele den med teamet.

Hva berettiger å ta opp en ADR?

Tenk på områder som organisasjonens arbeidsmåter i team, strukturen i programvaresystemet, koordinering på tvers av team, langsiktig vedlikeholdbarhet, eksterne grensesnitt, hvem du vil at skal ha nytte av den, og lignende.

Eksempelsvar: Vi vil lage en ADR når vi vil at framtidige utviklere skal forstå «hvorfor» bak det vi gjør.

Hva berettiger å la være å ta opp en ADR?

Tenk på områder som beslutninger som ikke handler om arkitektur, eller som er bittesmå, for eksempel med minimal risiko, selvstendige eller begrenset til én utvikler, eller som allerede er fullt dekket andre steder, for eksempel av standarder, retningslinjer eller dokumentasjon, eller som er midlertidige, for eksempel omveier, konseptbevis eller eksperimenter.

Eksempelsvar: Vi hopper over en ADR når en beslutning er begrenset i omfang, tid, risiko og kostnad, eller allerede er dekket andre steder.

Hva er livssyklusen til en ADR?

Tenk på områder som opprettingsprosessen, undersøkelsesprosessen, beslutningsprosessen, implementeringsprosessen og avviklingsprosessen. Tenk på hvordan du følger livssyklusen til ADR-en over tid, for eksempel hvordan du flytter ADR-en fra én tilstand til den neste, og hvordan du formidler dette til interessentene.

Eksempelsvar: Vi vil at en ADR skal ha fem livssyklustrinn: Oppstart → Undersøkelse → Evaluering → Implementering → Vedlikehold → Avvikling.

Hva er kriteriene for trinnene i livssyklusen til en ADR?

Tenk på områder som akseptkriterier for en ADR, det vil si hvordan du vet at den er god nok til å gå videre fra ett livssyklustrinn til det neste. Er problemet tydelig formulert? Er alternativene vurdert? Er avveiningene godt nok forstått og dokumentert? Er all relevant kontekst på plass? Er alle relevante interessenter involvert? Er alle tilbakemeldinger innarbeidet?

Eksempelsvar: Vi vil at interessentene skal stemme over en ADR når det aktive teamet har 1) fullført undersøkelsen, 2) fullført evalueringen, 3) publisert ADR-forslaget til interessentene med en forespørsel om kommentarer og en tidsramme på én uke, og 4) alle kommentarer fra interessentene er innarbeidet og besvart.

Hvilke roller og ansvar samhandler med en ADR?

Tenk på roller som forslagsstiller, undersøker, evaluator, gjennomgåer, godkjenner, vedlikeholder og lignende. Tenk på ansvar som kommunikasjon med interessenter, å sikre at forventningene oppfylles, deling på nettstedet eller intranettet, og å gjennomgå arbeidet jevnlig, og særlig når relevante endringer skjer.

Eksempelsvar: Vi vil at hver ADR alltid skal ha en primær kontaktperson, en sekundær kontaktperson og et ansvarlig team. De har ansvar for kommunikasjon, publisering, vedlikehold, jevnlig gjennomgang minst én gang i året og eventuell avvikling ved behov.

Hvordan samhandler styring med en ADR?

Tenk på områder som organisasjonens arbeidsmåter, eventuelle spesielle behov for etterlevelse, for eksempel av juridiske eller personalmessige forhold, og hvordan du vil håndtere konsensus versus konflikt versus eskalering. Finnes det områder, personer eller team som kan ha mer innflytelse enn andre når det gjelder en ADR, for eksempel ved at de kan godkjenne den, stemme over den eller nedlegge veto mot den?

Eksempelsvar: Styringen av en ADR følger denne prioriteringsrekkefølgen: administrerende direktør (CEO), teknisk direktør (CTO), juridisk direktør (CLO), teamet som implementerer en ADR og ekspertene på teamet som kan mest om AD-en. Ingen andre har styring, med mindre det er beskrevet i ADR-en.

Hvilke prinsipper samhandler med en ADR?

Tenk på områder som organisasjonens arbeidsmåter, blant annet å bevege seg raskt versus langsomt, for beslutningskonsensus versus beslutningskonflikt, for risikopreferanser versus sikkerhetspreferanser, offentlig diskusjon versus privat diskusjon og lignende.

Eksempelsvar: Vi bruker lederprinsippene handlingsorientering, uenig-og-forplikt (disagree-and-commit), 70 % sikre anslag er gode nok for beslutninger som lett kan omgjøres og lett kan isoleres, og åpne arbeidsmåter med unntak av konfidensiell informasjon som beskrevet i organisasjonens taushetsavtale.

Konsepter for neste steg for ADR-er

Arc42 svarer på to spørsmål på en pragmatisk måte og kan tilpasses dine behov. Hva bør du dokumentere/formidle om arkitekturen din? Hvordan bør du dokumentere/formidle? Arc42 omfatter arkitekturbeslutningslogger pluss veiledning om mål, begrensninger, kontekster, kvalitet, risikoer og mer.

C4-modellen er en lettlært, utviklervennlig tilnærming til diagrammer for programvarearkitektur. C4 er et sett med hierarkiske diagrammer for kontekst, containere, komponenter og kode, pluss støttediagrammer for systemlandskap, dynamikk og distribusjon.

Arkitekturdiagrammer, visninger og synspunkter

Et arkitekturdiagram kalles en «arkitekturvisning».

En «arkitekturvisning» er en instans av et «arkitektursynspunkt».

Et «arkitektursynspunkt» har en bestemt målgruppe med bestemte hensyn i tankene.

Eksempler på arkitektursynspunkter, visninger og diagrammer:

Beslektede diagrammer:

  • Et bruksområdediagram (use case-diagram) viser bruksområder til ledelsen/kundene, som kommer før kravene, som kommer før programvarearkitekturen.

  • Et distribusjonsdiagram viser den fysiske maskinvaren/datamaskinene som programvarekomponentene distribueres til.

  • Et dataflytdiagram viser hvordan data beveger seg gjennom systemet og transformeres.

  • Et sekvensdiagram brukes til å vise hvordan protokoller som HTTP fungerer på en tidsakse.

  • Et aktivitetsdiagram viser arbeidsflyten av aktiviteter et programvaresystem utfører, som en NPC-KI.

Egnethetsfunksjoner for beslutninger som kode

Egnethetsfunksjoner (fitness functions) er objektive, automatiserte kontroller, skrevet med programmeringskode, som verifiserer at beslutninger blir fulgt.

  • Egnethetsfunksjoner gjør beslutninger testbare og sikrer at de holdes.

  • Egnethetsfunksjoner for beslutninger kan hjelpe mye på kvalitetssikring, regulatoriske prosesser og styringsmål.

Hvordan egnethetsfunksjoner henger sammen med beslutninger

En beslutningslogg dokumenterer beslutningen, mens en egnethetsfunksjon sikrer beslutningen.

  • Eksempel på beslutning: Vi bruker event sourcing for å oppfylle revisjonskrav.

  • Eksempel på egnethetsfunksjon: Vi bruker serveren for kontinuerlig integrasjon til å teste at alle tilstandsendringer må gi hendelser.

Hvorfor egnethetsfunksjoner hjelper beslutninger

Objektive målinger: Egnethetsfunksjoner består eller feiler, så arbeidet blir synlig og tydelig.

Kontinuerlig bruk: Egnethetsfunksjoner er de levende reglene dine, og kjøres ved hver commit og hvert bygg.

Trygghet til å refaktorere: Egnethetsfunksjoner fanger automatisk opp feil mot beslutningsreglene.

Skalerbar styring: Egnethetsfunksjoner sikrer standarder uten å skape flaskehalser.

Kan egnethetsfunksjoner bruke KI?

Egnethetsfunksjoner kan bruke KI-språkmodeller (LLM-er) for beslutninger ved å stille spørsmål om arbeidet ditt, for eksempel planer, kode, skjemaer, API-er og mer:

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search.

This is a fitness function to evaluate if our work is
using all our decisions, and is correct and accurate.

- Our decisions are here: {url}
- Our work to evaluate is here: {url}

Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.

Enhetstesting av arkitektur

ArchUnit: sjekk arkitekturregler i Java-kode med et vanlig rammeverk for Java-enhetstester.

ArchUnitTS: sjekk arkitekturregler i TypeScript-kode og JavaScript-kode med Jest, Vitest, Jasmine og lignende.

Beslutningsrekkverk for pull requests

Decision Guardian viser automatisk de riktige beslutningsloggene i det riktige øyeblikket – når en utvikler aktivt endrer koden som disse beslutningene dekker. I stedet for å håpe at utviklere leser en dokumentmappe før de slår sammen, vises den relevante konteksten direkte på pull requesten.

Dette fungerer for alle typer beslutningslogger: arkitekturbeslutninger, databeslutninger, etterlevelsesbeslutninger, kliniske og medisinske beslutninger, sikkerhetsbeslutninger og mer.

Fungerer med alle CI-systemer (GitLab, Jenkins, CircleCI) og som pre-commit-hook. Åpen kildekode. MIT-lisens.

ADR Guard er en GitHub Action som får en pull request til å feile når overvåkede kodestier endres uten at en arkitekturbeslutningslogg er lagt til eller oppdatert. Unntak er eksplisitte: en linje med ADR-Exempt: og en begrunnelse slipper gjennom kontrollen og skrives inn i sammendraget for jobben. Malnøytral, ingen avhengigheter. Åpen kildekode. MIT-lisens.

Mer informasjon

Introduksjon:

Maler:

Fordypning:

Verktøy:

Bedriftsspesifikk veiledning:

Eksempler:

Videoer:

Podkaster:

Bøker:

Se også:

  • REMAP (Representation and Maintenance of Process Knowledge)

  • DRL (Decision Representation Language)

  • IBIS (Issue-Based Information System)

  • QOC (Questions, Options, and Criteria)

  • IBM’s e-Business Reference Architecture Framework

  • Decision Reasoning Format (DRF) - Et leverandørnøytralt, maskinlesbart YAML/JSON-format for å representere beslutninger med eksplisitt resonnement, forutsetninger, kognitiv tilstand og avveininger. Utfyller ADR-er ved å legge til strukturert, validerbart resonnement i dokumentasjonen av beslutninger.