Architecture Decision Record

Arkitekturbeslutspost (ADR)

Mallar, exempel och vägledning för att dokumentera arkitekturbeslut.

En arkitekturbeslutspost (ADR) är ett dokument som fångar ett viktigt arkitekturbeslut tillsammans med dess sammanhang och konsekvenser.

Översättningar: العربية, বাংলা, 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, 中文

  • Vad är en arkitekturbeslutspost?

    En arkitekturbeslutspost (architecture decision record, ADR) är ett dokument som fångar ett viktigt arkitekturbeslut som fattats tillsammans med dess sammanhang och…

  • Så kommer du igång med ADR:er

    För att komma igång med ADR:er, prata med dina teamkamrater om följande områden.

  • Tips för att skriva bra ADR:er

    Motivering: Förklara skälen till att fatta det specifika AD:t. Det kan omfatta sammanhanget (se nedan), för- och nackdelar med olika möjliga val, funktionsjämförelser…

  • ADR-exempelmallar

    ADR-mall av Michael Nygard (enkel och populär)

  • Råd om teamarbete för ADR:er

    Om du överväger att använda beslutsposter i ditt team finns här några råd som vi har lärt oss genom att arbeta med många team.

  • Lämplighetsfunktioner för beslut som kod

    Lämplighetsfunktioner (fitness functions) är objektiva automatiserade kontroller, skrivna med programmeringskod, som verifierar att beslut upprätthålls.

Gör din egen noggranna granskning av dessa resurser innan du använder dem i några kritiska system.

Innehåll:

Mallar:

Exempel:

Vad är en arkitekturbeslutspost?

En arkitekturbeslutspost (architecture decision record, ADR) är ett dokument som fångar ett viktigt arkitekturbeslut som fattats tillsammans med dess sammanhang och konsekvenser.

Ett arkitekturbeslut (architecture decision, AD) är ett programvarudesignval som adresserar ett betydande krav.

En arkitekturbeslutslogg (architecture decision log, ADL) är samlingen av alla ADR:er som skapats och underhålls för ett visst projekt (eller en organisation).

Ett arkitektoniskt betydelsefullt krav (architecturally-significant requirement, ASR) är ett krav som har en mätbar effekt på ett programvarusystems arkitektur.

Allt detta ryms inom ämnet arkitekturkunskapshantering (architecture knowledge management, AKM).

Målet med det här dokumentet är att ge en snabb översikt över ADR:er, hur man skapar dem och var man hittar mer information.

Förkortningar:

  • AD: arkitekturbeslut

  • ADL: arkitekturbeslutslogg

  • ADR: arkitekturbeslutspost

  • AKM: arkitekturkunskapshantering

  • ASR: arkitektoniskt betydelsefullt krav

Så kommer du igång med ADR:er

För att komma igång med ADR:er, prata med dina teamkamrater om följande områden.

Identifiering av beslut:

  • Hur brådskande och hur viktigt är AD:t?

  • Måste det fattas nu, eller kan det vänta tills mer är känt?

  • Både personlig och kollektiv erfarenhet, samt erkända designmetoder och praxis, kan hjälpa till vid identifiering av beslut.

  • Underhåll helst en att-göra-lista för beslut som kompletterar produktens att-göra-lista.

Beslutsfattande:

  • Det finns ett antal beslutstekniker, både generella och sådana som är specifika för programvaruarkitektur, till exempel dialogue mapping.

  • Gruppbeslut är ett aktivt forskningsämne.

Genomförande och upprätthållande av beslut:

  • AD:n används i programvarudesign; därför måste de kommuniceras till, och accepteras av, systemets intressenter som finansierar, utvecklar och driver det.

  • Arkitektoniskt tydliga kodstilar och kodgranskningar som fokuserar på arkitektoniska frågor och beslut är två relaterade metoder.

  • AD:n måste också (om)prövas när ett programvarusystem moderniseras i programvaruevolutionen.

Delning av beslut (valfritt):

  • Många AD:n återkommer i olika projekt.

  • Därför kan erfarenheter av tidigare beslut, både goda och dåliga, vara värdefulla återanvändbara tillgångar när man använder en explicit kunskapshanteringsstrategi.

Dokumentation av beslut:

  • Det finns många mallar och verktyg för att fånga beslut.

  • Se agila gemenskaper, till exempel M. Nygards ADR:er.

  • Se traditionella programvaruutvecklings- och arkitekturdesignprocesser, till exempel de tabelllayouter som föreslagits av IBM UMF och av Tyree och Akerman på CapitalOne.

För mer:

Så kommer du igång med ADR:er och verktyg

  • MySpec — Automatiserad plattform för specifikationer och arkitekturbeslut som strukturerar projektets konstitution, teknisk arkitektur och ADR:er i ren Markdown som levereras via MCP.

Du kan börja använda ADR:er med verktyg på vilket sätt du vill.

Till exempel:

  • Om du gillar att använda Google Drive och redigering online kan du skapa ett Google-dokument eller ett Google-kalkylblad.

  • Om du gillar versionshantering av källkod, till exempel git, kan du skapa en fil för varje ADR.

  • Om du gillar att använda projektplaneringsverktyg, till exempel Atlassian Jira, kan du använda verktygets planeringshanterare.

  • Om du gillar wikis, till exempel MediaWiki, kan du skapa en ADR-wiki.

Så kommer du igång med ADR:er och git

Om du gillar versionshantering med git, så här börjar vi gärna använda ADR:er med git för ett typiskt programvaruprojekt med källkod.

Skapa en katalog för ADR-filer:

$ mkdir adr

Skapa en textfil för varje ADR, till exempel database.txt:

$ vi database.txt

Skriv vad du vill i ADR:en. Se mallarna i det här repot för idéer.

Checka in ADR:en i ditt git-repo.

Claude Code-färdigheter för ADR:er

Det här arkivet innehåller två Claude Code-färdigheter (skills) under skills/, så att en AI-kodningsagent kan skriva och underhålla ADR:er på det sätt som det här projektet rekommenderar:

  • architecture-decision-record-skill — för allmänt bruk, för alla som skriver en ADR i vilket projekt som helst. Hjälper till att avgöra om ett beslut behöver en ADR, skapar en katalog adr/ eller decisions/, namnger filen, väljer en mall bland de elva medföljande skeletten och skriver solida avsnitt om sammanhang, beslut och konsekvenser.

  • architecture-decision-record-maintainer-skill — särskilt för dem som underhåller det här arkivet. Dokumenterar arkivets uppbyggnad, konventionen att spegla README och locales och de exakta stegen för att lägga till en ny mall, ett nytt exempel eller en ny verktygslänk.

För att använda en färdighet kopierar du dess mapp till .claude/skills/ i roten av det arkiv du arbetar i (eller till ~/.claude/skills/ för att göra den tillgänglig i alla projekt) och ber sedan Claude Code skriva eller granska en ADR.

Filnamnskonventioner

Om du väljer att skapa dina ADR:er med vanliga textfiler kanske du vill ta fram en egen filnamnskonvention för ADR-filer.

Vi föredrar att använda en filnamnskonvention med ett specifikt format.

Exempel:

  • choose-database.md

  • format-timestamps.md

  • manage-passwords.md

  • handle-exceptions.md

Vår filnamnskonvention:

  • Namnet har en verbfras i imperativ presens. Det underlättar läsbarheten och matchar vårt format för commit-meddelanden.

  • Namnet använder gemener och bindestreck (samma som detta repo). Det är en balans mellan läsbarhet och systemets användbarhet.

  • Filändelsen är markdown. Det kan vara användbart för enkel formatering.

Tips för att skriva bra ADR:er

Kännetecken för en bra ADR:

  • Motivering: Förklara skälen till att fatta det specifika AD:t. Det kan omfatta sammanhanget (se nedan), för- och nackdelar med olika möjliga val, funktionsjämförelser, diskussioner om kostnad/nytta och mer.

  • Specifik: Varje ADR bör handla om ett AD, inte flera AD:n.

  • Tidsstämplar: Ange när varje punkt i ADR:en skrevs. Detta är särskilt viktigt för aspekter som kan förändras över tid, såsom kostnader, scheman, skalning och liknande.

  • Oföränderlig: Ändra inte befintlig information i en ADR. Komplettera i stället ADR:en genom att lägga till ny information, eller ersätt ADR:en genom att skapa en ny ADR.

Kännetecken för ett bra avsnitt ”Sammanhang” i en ADR:

  • Förklara din organisations situation och affärsprioriteringar.

  • Ta med motiveringar och överväganden som bygger på dina teams sociala sammansättning och kompetenser.

  • Ta med relevanta för- och nackdelar och beskriv dem i termer som stämmer överens med dina behov och mål.

Kännetecken för ett bra avsnitt ”Konsekvenser” i en ADR:

  • Förklara vad som följer av beslutet. Det kan omfatta effekter, utfall, resultat, uppföljning och mer.

  • Ta med information om eventuella efterföljande ADR:er. Det är relativt vanligt att en ADR utlöser behov av fler ADR:er, till exempel när en ADR gör ett stort övergripande val som i sin tur skapar behov av fler mindre beslut.

  • Ta med eventuella processer för efterhandsutvärdering. Det är vanligt att team granskar varje ADR en månad senare för att jämföra ADR-informationen med vad som hänt i praktiken, för att lära och växa.

En ny ADR kan ersätta en tidigare ADR:

  • När ett AD fattas som ersätter eller upphäver en tidigare ADR bör en ny ADR skapas

ADR-exempelmallar

ADR-exempelmallar som vi har samlat in på nätet:

Råd om teamarbete för ADR:er

Om du överväger att använda beslutsposter i ditt team finns här några råd som vi har lärt oss genom att arbeta med många team.

Du har en möjlighet att leda dina teamkamrater genom att tillsammans prata om ”varför”, i stället för att kräva ”vad”. Beslutsposter är till exempel ett sätt för team att tänka smartare och kommunicera bättre; beslutsposter är inte värdefulla om de bara är ett påtvingat pappersarbete i efterhand.

Vissa team föredrar namnet ”beslut” (decisions) långt före förkortningen ”ADR:er”. När vissa team använder katalognamnet ”decisions” är det som om en glödlampa tänds, och teamet börjar lägga mer information i katalogen, till exempel leverantörsbeslut, planeringsbeslut, schemaläggningsbeslut och så vidare. Alla dessa typer av information kan använda samma mall. Vi antar att människor lär sig snabbare med ord (”beslut”) än med förkortningar (”ADR:er”), och att människor är mer motiverade att skriva dokument för pågående arbete när ordet ”post” (record) tas bort, och dessutom att vissa utvecklare och vissa chefer ogillar ordet ”arkitektur”.

I teorin är oföränderlighet idealiskt. I praktiken har föränderlighet fungerat bättre för våra team. Vi infogar den nya informationen i den befintliga ADR:en, med en datumstämpel och en anteckning om att informationen kom efter beslutet. Ett sådant tillvägagångssätt leder till ett ”levande dokument” som vi alla kan uppdatera. Typiska uppdateringar sker när vi får information tack vare nya teamkamrater, eller nya erbjudanden, eller verkliga resultat av vår användning, eller efterhandsändringar från tredje part, såsom leverantörers kapacitet, prisplaner, licensavtal och så vidare.

Teamarbetsfrågor för ADR:er

Vem kan skapa en ADR?

Tänk på områden som specifika personer, specifika roller, specifika team eller specifika avdelningar; överväg också om det finns personer, roller, team eller avdelningar som kan beställa en ADR, det vill säga begära en som någon annan kommer att skriva.

Exempelsvar: Vem som helst i vår organisation som har läst README-sidan om arkitekturbeslutsposter kan föreslå en ADR, vilket innebär att personen kan börja skriva den och dela den med teamet.

Vad motiverar att man tar upp en ADR?

Tänk på områden som din organisations teams arbetssätt, ditt programvarusystems struktur, samordning mellan team, långsiktig underhållbarhet, externa gränssnitt, vem du vill ska dra nytta, och liknande.

Exempelsvar: Vi vill skapa en ADR när vi vill att framtida utvecklare ska förstå ”varför” bakom det vi gör.

Vad motiverar att man inte tar upp en ADR?

Tänk på områden som beslut som inte handlar om arkitektur, eller är små, till exempel minimal risk eller fristående eller för en enda utvecklare, eller redan helt täcks någon annanstans, till exempel av standarder, policyer eller dokumentation, eller är tillfälliga, till exempel tillfälliga lösningar, koncepttest eller experiment.

Exempelsvar: Vi vill hoppa över en ADR när ett beslut är begränsat i omfattning, tid, risk och kostnad, eller redan täcks någon annanstans.

Vad är en ADR:s livscykel?

Tänk på områden som skapandeprocess, undersökningsprocess, beslutsprocess, genomförandeprocess och avvecklingsprocess. Överväg hur man spårar ADR:ens livscykel över tid, till exempel hur man flyttar ADR:en från ett tillstånd till nästa, och även hur man kommunicerar detta till intressenterna.

Exempelsvar: Vi vill att en ADR ska ha fem livscykelsteg: Inleda (Initiating) → Undersöka (Researching) → Utvärdera (Evaluating) → Genomföra (Implementing) → Underhålla (Maintaining) → Avveckla (Sunsetting).

Vilka är kriterierna för en ADR:s livscykelsteg?

Tänk på områden som godkännandekriterier för en ADR, det vill säga hur vet du att den är tillräckligt bra för att gå från ett livscykelsteg till nästa? Är problemet tydligt formulerat? Har alternativen övervägts? Är avvägningarna tillräckligt väl förstådda och dokumenterade? Finns allt relevant sammanhang på plats? Är alla relevanta intressenter involverade? Har all återkoppling arbetats in?

Exempelsvar: Vi vill att en ADR röstas om av intressenter när det aktiva teamet har 1) slutfört sin undersökning, 2) slutfört sin utvärdering, 3) publicerat ADR-förslaget för intressenterna med en begäran om kommentarer och en tidsram på en vecka, 4) alla kommentarer från intressenterna har arbetats in och åtgärdats.

Vilka roller och ansvar samverkar med en ADR?

Tänk på roller som förslagsställare, undersökare, utvärderare, granskare, godkännare, underhållare och liknande. Tänk på ansvar som kommunikation med intressenter, att säkerställa att förväntningar uppfylls, delning på webbplatsen eller intranätet och periodisk granskning av arbetet, särskilt när relevanta förändringar sker.

Exempelsvar: Vi vill att varje ADR alltid ska ha en primär kontaktperson, en sekundär kontaktperson och ett ansvarigt team; dessa ansvarar för kommunikation, publicering, underhåll, periodisk granskning minst en gång per år och eventuell avveckling vid behov.

Hur samverkar styrning med en ADR?

Tänk på områden som din organisations arbetssätt, eventuella särskilda efterlevnadsbehov, till exempel gällande juridiska aspekter eller personalaspekter, hur du vill hantera samsyn kontra konflikt kontra eskalering. Finns det områden eller personer eller team som kan ha större inflytande än andra när det gäller en ADR, till exempel genom att kunna godkänna den, rösta om den eller lägga in veto mot den?

Exempelsvar: Styrningen av en ADR sker i denna prioritetsordning: vd:n, teknikchefen, juridikchefen, teamet som genomför en ADR, experterna i teamet som har mest kunskap om ADD:n. Ingen annan har styrning om det inte beskrivs i ADR:en.

Vilka principer samverkar med en ADR?

Tänk på områden som din organisations arbetssätt, som omfattar att röra sig snabbt kontra att röra sig långsamt, beslutssamsyn kontra beslutskonflikt, och riskpreferenser kontra säkerhetspreferenser, offentlig diskussion kontra privat diskussion, och liknande.

Exempelsvar: Vi använder ledarskapsprinciperna handlingsbenägenhet (bias for action), oenighet-och-åtagande (disagree-and-commit), 70 % uppskattningar är tillräckligt bra för lätt reversibla, lätt isolerbara beslut, och offentliga arbetssätt med undantag för konfidentiell information såsom beskrivs i vår organisations sekretessavtal.

Nästa-steg-koncept för ADR:er

Arc42 besvarar två frågor pragmatiskt och kan anpassas efter dina behov. Vad bör du dokumentera/kommunicera om din arkitektur? Hur bör du dokumentera/kommunicera? Arc42 omfattar arkitekturbeslutsposter samt vägledning om mål, begränsningar, sammanhang, kvalitet, risker och mer.

C4-modellen är ett lättlärt, utvecklarvänligt sätt att rita diagram över programvaruarkitektur. C4 är en uppsättning hierarkiska diagram för kontext, containrar, komponenter och kod, plus stödjande diagram för systemlandskap, dynamik och driftsättning.

Arkitekturdiagram, vyer och synvinklar

Ett arkitekturdiagram kallas en "arkitekturvy".

En "arkitekturvy" är en instans av en "arkitektursynvinkel".

En "arkitektursynvinkel" har en specifik målgrupp med specifika angelägenheter i åtanke.

Exempel på arkitektursynvinklar, vyer och diagram:

Relaterade diagram:

  • Ett användningsfallsdiagram visar användningsfall för ledning/kunder, vilket föregår kraven, som föregår programvaruarkitekturen.

  • Ett driftsättningsdiagram visar den fysiska hårdvaran/de datorer som programvarukomponenterna driftsätts på.

  • Ett dataflödesdiagram visar hur data rör sig genom systemet och omvandlas.

  • Ett sekvensdiagram används för att visa hur protokoll som HTTP fungerar på en tidsaxel.

  • Ett aktivitetsdiagram skildrar arbetsflödet för de aktiviteter ett programvarusystem utför, som en NPC-AI.

Lämplighetsfunktioner för beslut som kod

Lämplighetsfunktioner (fitness functions) är objektiva automatiserade kontroller, skrivna med programmeringskod, som verifierar att beslut upprätthålls.

  • Lämplighetsfunktioner gör beslut testbara och säkerställbara.

  • Lämplighetsfunktioner för beslut kan i hög grad hjälpa kvalitetssäkring, regelefterlevnadsprocesser och styrningsmål.

Hur lämplighetsfunktioner hänger ihop med beslut

En beslutspost dokumenterar beslutet, medan en lämplighetsfunktion säkerställer beslutet.

  • Exempel på beslut: Vi använder event sourcing för granskningskrav.

  • Exempel på lämplighetsfunktion: Vi använder servern för kontinuerlig integration för att testa att alla tillståndsändringar måste ge upphov till händelser.

Varför lämplighetsfunktioner hjälper beslut

Objektiva mätningar: Lämplighetsfunktioner godkänns eller underkänns, så arbetet blir synligt och tydligt.

Kontinuerlig användning: Lämplighetsfunktioner är dina levande regler och körs vid varje commit och bygge.

Förtroende att refaktorera: Lämplighetsfunktioner fångar automatiskt fel i beslutsregler.

Skalbar styrning: Lämplighetsfunktioner säkerställer standarder utan att skapa flaskhalsar.

Kan lämplighetsfunktioner använda AI?

Lämplighetsfunktioner kan utnyttja AI-LLM:er för beslut genom att ställa frågor om ditt arbete, till exempel dina planer, kod, scheman, API:er och 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.

Enhetstestning av arkitektur

ArchUnit: kontrollera arkitekturregler för Java-kod med valfritt enkelt ramverk för Java-enhetstester.

ArchUnitTS: kontrollera arkitekturregler för TypeScript-kod och JavaScript-kod med Jest, Vitest, Jasmine och så vidare.

Beslutsräcken för pull requests

Decision Guardian visar automatiskt rätt beslutsposter i rätt ögonblick, nämligen när en utvecklare aktivt ändrar den kod som besluten täcker. I stället för att hoppas att utvecklare läser en dokumentmapp innan de slår ihop, dyker rätt sammanhang upp direkt i pull requesten.

Det här fungerar för alla slags beslutsposter: arkitekturbeslut, databeslut, efterlevnadsbeslut, kliniska och medicinska beslut, säkerhetsbeslut och mer.

Fungerar med alla CI-system (GitLab, Jenkins, CircleCI) och som pre-commit-hook. Öppen källkod. MIT-licens.

ADR Guard är en GitHub Action som får en pull request att misslyckas när bevakade kodsökvägar ändras utan att en arkitekturbeslutspost läggs till eller uppdateras. Undantag är uttryckliga: en ADR-Exempt:-rad med en orsak släpper igenom grinden och skrivs in i jobbets sammanfattning. Mallagnostisk, inga beroenden. Öppen källkod. MIT-licens.

Mer information

Introduktion:

Mallar:

Fördjupning:

Verktyg:

Företagsspecifik vägledning:

Exempel:

Videor:

Poddar:

Böcker:

Se även:

  • 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) - Ett leverantörsneutralt, maskinläsbart YAML/JSON-format för att representera beslut med uttryckligt resonemang, antaganden, kognitivt tillstånd och avvägningar. Kompletterar ADR:er genom att lägga till strukturerat, validerbart resonemang i beslutsdokumentationen.