Architecture Decision Record

Arkitekturbeslutningspost (ADR)

Skabeloner, eksempler og vejledning til at registrere arkitekturbeslutninger.

En arkitekturbeslutningspost (ADR) er et dokument, der fastholder en vigtig arkitekturbeslutning sammen med dens sammenhæng og konsekvenser.

Oversættelser: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, Ελληνικά, 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, 中文

Gør din egen rettidige omhu med disse ressourcer, før du bruger dem i kritiske systemer.

Indhold:

Skabeloner:

Eksempler:

Hvad er en arkitekturbeslutningspost?

En arkitekturbeslutningspost (ADR) er et dokument, der registrerer en vigtig arkitekturbeslutning, der er truffet, sammen med dens kontekst og konsekvenser.

En arkitekturbeslutning (AD) er et softwaredesignvalg, der adresserer et væsentligt krav.

En arkitekturbeslutningslog (ADL) er samlingen af alle ADR'er, der er oprettet og vedligeholdt for et bestemt projekt (eller en bestemt organisation).

Et arkitektonisk væsentligt krav (ASR) er et krav, der har en målbar effekt på arkitekturen i et softwaresystem.

Alt dette hører under emnet arkitekturvidensstyring (AKM).

Formålet med dette dokument er at give et hurtigt overblik over ADR'er, hvordan man skriver dem, og hvor man finder flere oplysninger.

Forkortelser:

  • AD: arkitekturbeslutning

  • ADL: arkitekturbeslutningslog

  • ADR: arkitekturbeslutningspost

  • AKM: arkitekturvidensstyring

  • ASR: arkitektonisk væsentligt krav

Sådan kommer du i gang med ADR'er

For at komme i gang med ADR'er kan du tale med dine teamkolleger om følgende områder.

Identificering af beslutninger:

  • Hvor presserende og hvor vigtig er AD'en?

  • Skal beslutningen træffes nu, eller kan den vente, til mere er kendt?

  • Personlig og kollektiv erfaring samt anerkendte designmetoder og -praksisser kan hjælpe med at identificere beslutninger.

  • Hold ideelt set en beslutningsbacklog, der supplerer produktbackloggen.

Beslutningstagning:

  • Der findes flere teknikker til beslutningstagning, både generelle teknikker og teknikker, der er specifikke for softwarearkitektur. Et eksempel er dialogkortlægning.

  • Gruppebeslutningstagning er et aktivt forskningsemne.

Håndhævelse og gennemførelse af beslutninger:

  • Da AD'er bruges i softwaredesign, skal de kommunikeres til og accepteres af de interessenter, der finansierer, udvikler og driver systemet.

  • Arkitekturbevidste kodestile og kodegennemgange med fokus på arkitekturrelaterede forhold og beslutninger er to beslægtede praksisser.

  • AD'er bør også (gen)overvejes, når et softwaresystem moderniseres under softwareudviklingens forløb.

Deling af beslutninger (valgfrit):

  • Mange AD'er gentages på tværs af projekter.

  • Derfor kan erfaring med tidligere beslutninger, både gode og dårlige, være et værdifuldt genanvendeligt aktiv, når man bruger en eksplicit strategi for videnstyring.

Dokumentation af beslutninger:

  • Der findes mange skabeloner og værktøjer til at registrere beslutninger.

  • Se det agile miljø, for eksempel M. Nygards ADR'er.

  • Se traditionelle softwareudviklings- og arkitekturdesignprocesser, for eksempel IBM UMF og tabellayoutet foreslået af Tyree og Akerman fra CapitalOne.

Læs mere:

Sådan kommer du i gang med ADR'er med værktøjer

  • MySpec — Automatiseret specifikations- og arkitekturbeslutningsplatform, der strukturerer projektets forfatning, teknisk arkitektur og ADR'er i ren Markdown leveret via MCP.

Du kan selv vælge, hvordan du kommer i gang med ADR'er med værktøjer.

For eksempel:

  • Hvis du kan lide Google Drev og onlineredigering, kan du oprette et Google-dokument eller et Google-regneark.

  • Hvis du kan lide kildekodeversionsstyring som git, kan du oprette en fil for hver ADR.

  • Hvis du kan lide projektplanlægningsværktøjer som Atlassian Jira, kan du bruge deres planlægningstracker.

  • Hvis du kan lide wikier som MediaWiki, kan du oprette en ADR-wiki.

Sådan kommer du i gang med ADR'er med git

Hvis du kan lide git-versionsstyring, er her, hvordan vi kommer i gang med ADR'er med git i et typisk softwareprojekt med kildekode.

Opret en mappe til dine ADR-filer:

$ mkdir adr

Opret en tekstfil for hver ADR, for eksempel database.txt:

$ vi database.txt

Skriv hvad du vil i ADR'en. For idéer kan du se skabelonerne i dette repository.

Commit ADR'erne til dit git-repository.

Claude Code-færdigheder til ADR'er

Dette lager indeholder to Claude Code-færdigheder (skills) under skills/, så en AI-kodeagent kan skrive og vedligeholde ADR'er på den måde, dette projekt anbefaler:

  • architecture-decision-record-skill — til generelt brug, for alle der skriver en ADR i et hvilket som helst projekt. Hjælper med at afgøre, om en beslutning kræver en ADR, opretter en adr/- eller decisions/-mappe, navngiver filen, vælger en skabelon blandt de elleve medfølgende skelet og skriver solide afsnit om sammenhæng/beslutning/konsekvenser.

  • architecture-decision-record-maintainer-skill — specifikt til vedligeholdere af dette lager. Dokumenterer lagerets opbygning, konventionen om at spejle README/locales og de præcise trin til at tilføje en ny skabelon, et nyt eksempel eller et nyt værktøjslink.

For at bruge en færdighed skal du kopiere dens mappe til .claude/skills/ i roden af det lager, du arbejder i (eller til ~/.claude/skills/ for at gøre den tilgængelig i alle projekter) og derefter bede Claude Code om at skrive eller gennemgå en ADR.

Konventioner for filnavne

Hvis du vælger at skrive ADR'er som almindelige tekstfiler, kan det være nyttigt at fastlægge din egen konvention for ADR-filnavne.

Vi foretrækker en konvention for filnavne med et bestemt format.

Eksempler:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Vores konvention for filnavne:

  • Navnet er en bydemåde i nutid. Det forbedrer læsbarheden og passer til vores format for commit-beskeder.

  • Navnet bruger små bogstaver og bindestreger (ligesom i dette repository). Det er en balance mellem læsbarhed og brugbarhed på tværs af systemer.

  • Filendelsen er markdown. Det kan være praktisk til enkel formatering.

Forslag til at skrive gode ADR'er

Kendetegn ved en god ADR:

  • Begrundelse: forklar, hvorfor AD'en udføres. Det kan omfatte kontekst (se nedenfor), fordele og ulemper ved forskellige mulige valg, funktionssammenligninger, cost-benefit-diskussioner og så videre.

  • Specifik: hver ADR bør handle om én AD, ikke flere AD'er.

  • Tidsstemplet: angiv, hvornår hvert element i ADR'en blev skrevet. Det er især vigtigt for aspekter, der kan ændre sig over tid, såsom omkostninger, tidsplan, udvidelse og så videre.

  • Uforanderlig: ændr ikke eksisterende oplysninger i en ADR. Ændr i stedet ADR'en ved at tilføje nye oplysninger, eller erstat ADR'en ved at oprette en ny ADR.

Kendetegn ved et godt afsnit om "Kontekst" i en ADR:

  • Beskriver organisationens situation og forretningsmæssige prioriteter.

  • Indeholder begrundelsen og overvejelserne baseret på teamets sociale og tekniske sammensætning.

  • Indeholder relevante afvejninger, udtrykt i termer der passer til behov og mål.

Kendetegn ved et godt afsnit om "Konsekvenser" i en ADR:

  • Beskriver, hvad der følger af at træffe beslutningen. Det kan omfatte effekter, resultater, leverancer, opfølgende handlinger og så videre.

  • Indeholder oplysninger om opfølgende ADR'er. Det er relativt almindeligt, at én ADR udløser behovet for flere ADR'er. For eksempel kan en ADR, der træffer et stort, overordnet valg, udløse behov for mindre beslutninger.

  • Indeholder en efterbehandlingsproces. Det er almindeligt, at teams gennemgår hver ADR efter en måned, sammenligner ADR-oplysningerne med det, der rent faktisk skete, og lærer og vokser heraf.

En ny ADR kan erstatte en tidligere ADR:

  • Når der træffes en AD, der erstatter eller ugyldiggør en tidligere ADR, bør der skrives en ny ADR

ADR-eksempelskabeloner

ADR-eksempelskabeloner, som vi har samlet fra nettet:

Teamarbejdsråd til ADR'er

Hvis du overvejer at bruge beslutningsposter i dit team, er her nogle råd, vi har lært ved at arbejde med flere teams.

Der er mulighed for at lede teammedlemmer ved at tale om "hvorfor" frem for at gennemtvinge "hvad". Beslutningsposter er for eksempel en måde for teams at tænke klogere og kommunikere bedre. Hvis beslutningsposter blot er et papirarbejdskrav, der gennemtvinges bagefter, har de ingen værdi.

Nogle teams foretrækker i høj grad navnet "beslutninger" frem for forkortelsen "ADR". Når nogle teams bruger "decisions" som mappenavn, går der et lys op, og teams begynder at lægge flere oplysninger i mappen, såsom leverandørbeslutninger, planbeslutninger, tidsplanbeslutninger og så videre. Du kan bruge den samme skabelon til alle disse slags oplysninger. Vi antager, at folk lærer hurtigere med ordet ("beslutning") end med forkortelsen ("ADR"), at udeladelsen af ordet "post" giver mere motivation til at skrive igangværende arbejde, og at nogle udviklere og nogle ledere ikke bryder sig om ordet "arkitektur".

I teorien er uforanderlighed ideel. I praksis fungerede foranderlighed bedre for vores team. Vi indsætter nye oplysninger i en eksisterende ADR med et datostempel og en note om, at oplysningerne kom ind efter beslutningen. Denne tilgang fører til et "levende dokument", som vi alle kan opdatere. Typiske opdateringer kommer fra at få oplysninger takket være nye teammedlemmer, nye tilbud, faktiske resultater af vores brug eller efter efterfølgende ændringer fra tredjepart såsom leverandørers funktioner, prisplaner og licensaftaler.

Teamwork-spørgsmål til ADR'er

Hvem kan skrive ADR'er?

Overvej områder som bestemte personer, bestemte roller, bestemte teams, bestemte afdelinger. Overvej også, om der er personer, roller, teams eller afdelinger, der kan bestille ADR'er, dvs. kan anmode om, at en anden skriver en ADR.

Eksempel på svar: enhver i vores organisation, der har læst README-siden om arkitekturbeslutningsposter, kan foreslå en ADR, dvs. begynde at skrive og dele den med teamet.

Hvad retfærdiggør at rejse en ADR?

Overvej områder som hvordan teams i organisationen arbejder, softwaresystemers struktur, koordinering mellem teams, langsigtet vedligeholdelighed, eksterne grænseflader og hvem du vil have til at drage fordel.

Eksempel på svar: vi vil gerne skrive en ADR, når vi ønsker, at fremtidige udviklere skal forstå "hvorfor" bag det, vi gør.

Hvad retfærdiggør ikke at rejse en ADR?

Overvej områder som beslutninger, der ikke handler om arkitektur, beslutninger, der er trivielle, fordi de har minimal risiko, er selvstændige eller begrænset til én udvikler, beslutninger, der allerede er fuldt dækket andetsteds i standarder, politikker, dokumentation og så videre, eller beslutninger, der er midlertidige, såsom nødløsninger, proofs of concept og eksperimenter.

Eksempel på svar: vi vil gerne springe en ADR over, når beslutningen er begrænset i omfang, tid, risiko og omkostninger eller allerede er dækket andetsteds.

Hvad er en ADR's livscyklus?

Overvej områder som skriveprocessen, undersøgelsesprocessen, beslutningsprocessen, implementeringsprocessen og udfasningsprocessen. Overvej, hvordan du sporer ADR'ens livscyklus over tid, for eksempel hvordan du flytter en ADR fra én status til den næste, og hvordan du kommunikerer det til interessenter.

Eksempel på svar: vi vil gerne have, at ADR'er har fem livscyklusfaser: Initiating → Researching → Evaluating → Implementing → Maintaining → Sunsetting.

Hvad er kriterierne for en ADR's livscyklusfaser?

Overvej områder som acceptkriterier for ADR'er, dvs. hvordan ved vi, at en ADR er god nok til at gå fra én livscyklusfase til den næste? Er problemet klart beskrevet? Er alternativer overvejet? Er afvejningerne godt forstået og dokumenteret? Er al relevant kontekst til stede? Er alle relevante interessenter involveret? Er al feedback blevet indarbejdet?

Eksempel på svar: vi vil gerne have, at det aktive team 1) afslutter undersøgelsen, 2) afslutter evalueringen, 3) offentliggør ADR-forslagene for interessenter med en anmodning om kommentarer og en tidsfrist på en uge, og 4) når alle interessentkommentarer er indarbejdet og behandlet, lader interessenterne stemme om ADR'en.

Hvilke roller og ansvarsområder samspiller med ADR'er?

Overvej roller som indsender, undersøger, evaluator, gennemgående, godkender og vedligeholder. Overvej ansvarsområder som at kommunikere med interessenter, sikre at forventninger indfris, dele på webstedet eller intranettet og periodisk gennemgå arbejdet, især når der er relevante ændringer.

Eksempel på svar: vi vil gerne have, at hver ADR altid har en primær ejer, en sekundær ejer og et ansvarligt team. De er ansvarlige for kommunikation, offentliggørelse, vedligeholdelse, periodisk gennemgang mindst årligt og endelig udfasning efter behov.

Hvordan samspiller governance med ADR'er?

Overvej områder som hvordan organisationen arbejder, særlige compliancebehov såsom juridiske aspekter eller HR-aspekter, og hvordan du vil håndtere konsensus versus konflikt versus eskalering. Er der områder, personer eller teams, der kan have mere indflydelse end andre, såsom magten til at godkende, stemme eller nedlægge veto i forbindelse med ADR'er?

Eksempel på svar: governance for en ADR følger denne prioritetsrækkefølge: CEO, CTO, CLO, teamet der implementerer ADR'en, den mest vidende ekspert i teamet om ADD'en. Ingen har governance, medmindre det er beskrevet i ADR'en.

Hvilke principper samspiller med ADR'er?

Overvej områder, der involverer, hvordan organisationen arbejder, såsom at bevæge sig hurtigt eller langsomt, beslutningskonsensus versus beslutningskonflikt, risikopræference versus sikkerhedspræference og offentlig diskussion versus privat diskussion.

Eksempel på svar: vi bruger lederskabsprincipperne handlingsorientering (bias for action), uenighed og forpligtelse (disagree-and-commit), 70 % af oplysningerne er nok til beslutninger, der er lette at gøre om og lette at isolere, og åbent arbejde bortset fra fortrolige oplysninger som beskrevet i vores organisations fortrolighedsaftaler.

Næste-skridt-begreber til ADR'er

Arc42 besvarer to spørgsmål pragmatisk og kan tilpasses dine konkrete behov. Hvad bør du dokumentere/kommunikere om din arkitektur? Hvordan bør du dokumentere/kommunikere? Arc42 omfatter arkitekturbeslutningsposter samt vejledning om mål, begrænsninger, kontekster, kvalitet, risici med mere.

C4-modellen er en let at lære, udviklervenlig tilgang til at tegne softwarearkitekturdiagrammer. C4 er et sæt hierarkiske diagrammer for kontekst, containere, komponenter og kode samt understøttende diagrammer for systemlandskab, dynamik og udrulning.

Arkitekturdiagrammer, visninger og synsvinkler

Et arkitekturdiagram kaldes en "arkitekturvisning".

En "arkitekturvisning" er en forekomst af et "arkitektursynspunkt".

Et "arkitektursynspunkt" har en bestemt målgruppe med bestemte bekymringer for øje.

Eksempler på arkitektursynspunkter, visninger og diagrammer:

Relaterede diagrammer:

  • Et use case-diagram viser use cases for ledelsen/kunderne, hvilket går forud for kravene, som går forud for softwarearkitekturen.

  • Et udrulningsdiagram viser den fysiske hardware/de fysiske computere, som softwarekomponenterne udrulles til.

  • Et dataflowdiagram viser, hvordan data bevæger sig gennem systemet og transformeres.

  • Et sekvensdiagram bruges til at vise, hvordan protokoller som HTTP fungerer på en tidsakse.

  • Et aktivitetsdiagram afbilder arbejdsgangen for de aktiviteter, et softwaresystem udfører, som en NPC-AI.

Fitnessfunktioner for beslutninger som kode

En fitnessfunktion er en objektiv, automatiseret kontrol, skrevet som programkode, der verificerer, at en beslutning overholdes.

  • Fitnessfunktioner gør beslutninger testbare og kontrollerbare.

  • Fitnessfunktioner for beslutninger kan være en stor hjælp til kvalitetssikring, regulatoriske processer og governance-mål.

Sådan hænger fitnessfunktioner og beslutninger sammen

En beslutningspost dokumenterer en beslutning; en fitnessfunktion håndhæver den beslutning.

  • Eksempel på beslutning: brug event sourcing til revisionskrav.

  • Eksempel på fitnessfunktion: brug en kontinuerlig integrationsserver til at teste, at enhver tilstandsændring skal generere en hændelse.

Hvorfor fitnessfunktioner hjælper beslutninger

Objektiv måling: en fitnessfunktion består eller fejler, så arbejdet er synligt og tydeligt.

Løbende brug: en fitnessfunktion er en levende regel og kører ved hver commit og build.

Tillid ved refaktorering: en fitnessfunktion fanger automatisk fejl i forhold til beslutningsreglerne.

Skalerbar governance: en fitnessfunktion håndhæver standarder uden at skabe flaskehalse.

Kan fitnessfunktioner bruge AI?

En fitnessfunktion kan bruge en AI-LLM til beslutninger ved at stille spørgsmål om vores arbejde, såsom planer, kode, skemaer, API'er og så videre:

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.

Arkitekturenhedstests

ArchUnit: kontrollér arkitekturregler for Java-kode med et almindeligt Java-enhedstestframework.

ArchUnitTS: kontrollér arkitekturregler for TypeScript-kode og JavaScript-kode med Jest, Vitest, Jasmine og andre.

Beslutningsautoværn til pull requests

Decision Guardian fremhæver automatisk de rette beslutningsposter på det rette tidspunkt, nemlig når en udvikler aktivt ændrer den kode, som disse beslutninger dækker. I stedet for at håbe på, at udviklere læser en dokumentmappe før en sammenfletning, vises den relevante sammenhæng direkte på pull requesten.

Det fungerer for alle slags beslutningsposter: arkitekturbeslutninger, databeslutninger, compliancebeslutninger, kliniske og medicinske beslutninger, sikkerhedsbeslutninger og flere.

Fungerer med ethvert CI-system (GitLab, Jenkins, CircleCI) og som en pre-commit-hook. Open source. MIT-licens.

ADR Guard er en GitHub Action, der afviser en pull request, når overvågede kodestier ændres uden at en arkitekturbeslutningspost tilføjes eller opdateres. Undtagelser er eksplicitte: en ADR-Exempt:-linje med en begrundelse lader porten passere og skrives i jobbets opsummering. Skabelonuafhængig, ingen afhængigheder. Open source. MIT-licens.

Mere information

Introduktion:

Skabeloner:

Dybdegående:

Værktøjer:

Virksomhedsspecifik vejledning:

Eksempler:

Videoer:

Podcasts:

Bøger:

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ørneutralt, maskinlæsbart YAML/JSON-format til at repræsentere beslutninger med eksplicit ræsonnement, antagelser, kognitiv tilstand og afvejninger. Supplerer ADR'er ved at tilføje struktureret, validerbart ræsonnement til beslutningsdokumentation.