Det är 6 månader in i projektet. En ny utvecklare går med i teamet och ställer en rimlig fråga:
“Varför använder vi Postgres istället för MongoDB?”
Du pausar. Du kommer ihåg att det fanns en diskussion. Någon hade starka åsikter. Det fanns avvägningar. Men detaljerna? Borta. Förlorade i en Slack-tråd från mars som du skulle behöva scrolla genom 1000 meddelanden för att hitta.
Så du ger det värsta möjliga svaret: “Jag tror det var för att… något om transaktioner? Kanske fråga Sarah—vänta, Sarah slutade förra månaden.”
Nu är den nya utvecklaren förvirrad. De börjar ifrågasätta valet. Ganska snart föreslår någon “Kanske borde vi byta till MongoDB.” Och ni är tillbaka i samma debatt ni redan hade, och bränner tid med att omvärdera ett beslut ni fattade för sex månader sedan.
Detta är varför vi dokumenterar beslut.
Inte för att skapa byråkrati. Inte för att tillfredsställa någon compliance-checklista. Men för att bevara varför bakom tekniska val så team inte slösar tid med att omförhandla vad de redan bestämt.
Presenterar: Architecture Decision Records (ADR:er).
Vad är en ADR?
En Architecture Decision Record är ett kort dokument som fångar:
- Vad beslut fattades (t.ex. “Använd Postgres för primär datalagring”)
- Varför det fattades (t.ex. “Behöver ACID-transaktioner, befintlig teamexpertis”)
- Vilka alternativ övervägdes (t.ex. MongoDB, DynamoDB)
- Vilka konsekvenser följer av detta val (t.ex. “Pro: Stark konsistens. Con: Svårare att skala horisontellt”)
Det är allt. Inga diagram. Ingen UML. Ingen 10-sidors teknisk spec. Bara:
- Kontext: Varför fattar vi detta beslut?
- Beslut: Vad valde vi?
- Alternativ: Vad annat övervägde vi?
- Konsekvenser: Vilka är avvägningarna?
ADR:er lever i din repo, vanligtvis i .assistant/adr/ eller docs/adr/, och de numreras sekventiellt: ADR-001, ADR-002, etc.
Varför ADR:er spelar roll
1. Förhindra omförhandlingar
Utan ADR:er omförhandlar team beslut varje gång:
- En ny person går med
- Någon glömmer varför ett val gjordes
- Ett liknande problem kommer upp och folk vill “återbesöka tillvägagångssättet”
Med ADR:er svarar du: “Vi valde Postgres i ADR-003. Här är varför. Om förutsättningarna har förändrats, låt oss skriva ADR-015 för att återbesöka det.”
Nu bygger ni på tidigare beslut istället för att omprocessa dem.
2. Bevara kontext
Sex månader från nu kommer du inte komma ihåg varför du valde JWT över sessioner. Men ADR-007 kommer. Den fångar kontexten (stateless API:er), avvägningarna (inget server-side sessionlager, men tokens kan inte återkallas enkelt), och resonemanget.
Framtida du är tacksam.
3. Onboarda nya teammedlemmar
Nya utvecklare läser ADR:erna och förstår arkitekturens historia på en timme istället för att pussla ihop det över tre veckor genom att läsa kod och ställa frågor.
De lär sig:
- Varför databasen är Postgres (ADR-003)
- Varför auth använder JWT (ADR-007)
- Varför vi deployer till AWS istället för GCP (ADR-011)
- Varför vi valde REST över GraphQL (ADR-005)
De förstår inte bara vad systemet är, utan varför det designades så.
4. Möjliggör bättre beslut
När du dokumenterar beslut tvingar du dig själv att artikulera avvägningarna. Detta synliggör antaganden och fångar dåligt resonemang innan det blir kod.
Att skriva “Vi valde MongoDB för att det är webscale” tvingar dig att inse att det inte är en riktig anledning. Att skriva “Vi valde MongoDB för att vi behöver flexibel schemaevolution och inte kräver transaktioner” är en riktig anledning du kan utvärdera.
5. Gör “återbesök” ärligt
Ibland behöver du ändra ett beslut. Kanske ändrades kraven. Kanske lärde du dig något nytt. Kanske var det ursprungliga valet fel.
ADR:er gör detta legitimt. Du skriver ADR-015: “Ersätt ADR-003 (Postgres) — Migrera till MongoDB för flexibla schemabehov.”
Nu är det tydligt:
- Vi fattade ett val (ADR-003)
- Förutsättningar förändrades (dokumenterat i ADR-015)
- Vi vänder medvetet på det (inte vacklar)
Detta förhindrar beslutsflackning där team studsar mellan val utan att lära sig.
ADR-mallen
Här är den minimala ADR-strukturen:
# ADR-XXX — [Kort titel på beslut]
**Datum:** ÅÅÅÅ-MM-DD
**Status:** Föreslagen | Godkänd | Föråldrad | Ersatt av ADR-YYY
## Kontext
Vad är situationen? Vilket problem löser vi? Vilka begränsningar finns?
## Beslut
Vad bestämde vi? Var specifik. Namnge teknologier, mönster, tillvägagångssätt.
## Övervägda alternativ
Vad mer tittade vi på? Varför valde vi inte dem?
## Konsekvenser
### För
- Vilka fördelar kommer från detta beslut?
### Emot
- Vilka avvägningar eller risker accepterar vi?
### Neutralt
- Vad förändras men är inte strikt bra eller dåligt?
Det är 5 sektioner. Total skrivtid: 10-15 minuter. Totalt värde: månader av sparad tid.
Verkligt exempel: Databasval
Här är en ADR för ett verkligt tekniskt beslut:
# ADR-003 — Använd Postgres för primär datalagring
**Datum:** 2026-02-15
**Status:** Godkänd
## Kontext
Vi behöver en databas för användarkonton, autentiseringstillstånd och applikationsdata. Krav:
- Måste stödja ACID-transaktioner (betalningsbearbetning kräver konsistens)
- Måste hantera strukturerad relationsdata (användare → roller → behörigheter)
- Måste skala till 10k samtidiga användare initialt
- Teamet har Postgres-erfarenhet men begränsad NoSQL-erfarenhet
- Budget: $50-200/månad för hanterad databas
## Beslut
Använd **PostgreSQL 16** (hanterad via AWS RDS) som primärt datalager.
## Övervägda alternativ
### MongoDB
- **För:** Flexibelt schema, horisontellt skalbar, bra för snabb iteration
- **Emot:** Inga multi-dokument-transaktioner (tillagt i 4.0 men mindre moget än Postgres), teamet har ingen produktionserfarenhet, svårare att köra relationsdata
- **Slutsats:** Uppfyller inte ACID-krav för betalningar
### DynamoDB
- **För:** Helt hanterad, skalar utan ansträngning, pay-per-request-prissättning
- **Emot:** Inga joins, inga komplexa queries, dyrt i skala, brant inlärningskurva, dålig passform för relationsdatamodell
- **Slutsats:** Fel verktyg för relationsanvändningsfall
### MySQL
- **För:** Mogen, brett stödd, liknande Postgres
- **Emot:** Mindre avancerade funktioner (JSONB, full-textsökning, array-typer), licensoro (Oracle-ägande)
- **Slutsats:** Postgres erbjuder bättre funktionsset för våra behov
## Konsekvenser
### För
- Starka ACID-garantier för betalningstransaktioner
- Mogen relationsmodell passar vår datastruktur (användare, roller, sessioner)
- Teamet känner redan Postgres (snabbare utveckling, färre misstag)
- JSONB-stöd tillåter flexibelt schema vid behov
- Rikt ekosystem (pgBouncer för connection pooling, PostGIS om vi lägger till platsfunktioner)
### Emot
- Vertikala skalningsbegränsningar (behöver eventuellt read replicas om trafik överskrider single-instance-kapacitet)
- Något långsammare skrivprestanda än NoSQL för ostrukturerad data
- AWS RDS lägger till ~$50/månad kostnad (vs gratis-tier MongoDB Atlas)
### Neutralt
- Migrering till annan databas skulle kräva betydande ombyggnad (inte en kortsiktig oro)
- Kräver connection pooling-strategi för hög samtidighet (planerat: pgBouncer)
När man ska skriva en ADR
Skriv en ADR när du fattar ett beslut som:
1. Påverkar systemarkitektur
- Databasval
- Autentiseringsstrategi
- API-design (REST vs GraphQL vs gRPC)
- Hostingplattform (AWS vs GCP vs själv-hostad)
- Ramverksval (React vs Vue, Express vs Fastify)
2. Har långsiktiga konsekvenser
- Licensbeslut (öppen källkod vs proprietär)
- Datalagringspolicys
- Infrastrukturmönster (mikrotjänster vs monolit)
- CI/CD-pipeline-design
3. Involverar betydande avvägningar
- Prestanda vs utvecklarerfarenhet
- Säkerhet vs bekvämlighet
- Kostnad vs skalbarhet
- Flexibilitet vs enkelhet
4. Kräver teamkonsensus
Om du behöver diskutera det i ett möte behöver du en ADR. Skriv ner beslutet efteråt.
Skriv INTE ADR:er för…
Implementeringsdetaljer: Dokumentera inte “Vi använde en for-loop istället för .map()” — det är kod, inte arkitektur.
Uppenbara val: Skriv inte “Använd Git för versionskontroll” såvida det inte finns ett verkligt alternativ du övervägde.
Tillfälliga workarounds: Dokumentera inte “Vi lade till ett hack för att fixa buggen” — det är teknisk skuld, inte ett beslut du försvarar.
Personliga preferenser: Skriv inte “Vi använder tabs istället för spaces” — det är en stilguide, inte arkitektur.
Hur man skriver ADR:er utan att sakta ner
#1-klagomålet om ADR:er: “Vi har inte tid att skriva dokumentation.”
Här är hur man håller ADR:er lättviktiga:
1. Skriv dem omedelbart efter beslut (5 minuter)
Vänta inte till slutet av sprinten. Skriv ADR:n direkt efter beslutet, medan kontexten är färsk. Det tar 5 minuter nu eller 30 minuter senare när du glömt detaljerna.
2. Använd en mall (fyll i tomrum)
Kopiera din mall, fyll i tomrummen. Övertänk inte det.
cp .assistant/adr/ADR-TEMPLATE.md .assistant/adr/ADR-012.md
3. Var koncis (max 1 sida)
Om din ADR är över 1 sida skriver du en spec, inte en beslutspost. Komprimera.
4. Länka, duplicera inte (referera externa dokument)
Klistra inte in kodexempel eller detaljerade implementeringsanteckningar. Länka till dem.
Se [JWT-implementeringsguide](https://auth-docs.example.com/jwt) för detaljer.
5. Utkast i möten (fånga beslut i realtid)
Under arkitekturdiskussioner, låt någon utkasta ADR:n i ett delat dokument. I slutet av mötet är den 80% klar. Polera den senare.
Underhålla ADR:er över tid
ADR:er är inte hugget i sten. De utvecklas.
Statusar
- Föreslagen: Under diskussion, inte ännu beslutat
- Godkänd: Beslutat och implementerat
- Föråldrad: Inte längre relevant (t.ex. “använd MySQL” → vi är nu på Postgres)
- Ersatt av ADR-XXX: Ersatt av ett nyare beslut
Uppdatera vs skapa nya ADR:er
Redigera inte gamla ADR:er (förstör historik). Istället:
- Markera gammal ADR som “Ersatt av ADR-XXX”
- Skriv ny ADR som förklarar ändringen och varför
- Länka dem tillsammans
Exempel:
# ADR-003 — Använd Postgres för primär datalagring
**Status:** Ersatt av ADR-018 (Migrerad till Aurora Serverless)
Nu är historiken tydlig: vi valde Postgres (ADR-003), förutsättningar förändrades (hög trafik + kostnad), vi bytte till Aurora (ADR-018).
Verkliga ADR:er från verkligheten
Låt oss titta på tre mer realistiska exempel:
ADR-007: JWT vs sessionsbaserad auth
# ADR-007 — Använd JWT-tokens för autentisering
**Datum:** 2026-02-20
**Status:** Godkänd
## Kontext
Behöver stateless autentisering för API som betjänar webb + mobilklienter. Måste skala horisontellt utan delat sessionlager.
## Beslut
Använd **JWT-tokens** (RS256-signering) med 24-timmars utgång + 30-dagars refresh tokens.
## Alternativ
**Sessionsbaserad auth (cookie + Redis):**
- För: Tokens återkallbara omedelbart
- Emot: Kräver delat Redis, stateful, svårare att skala
**Endast OAuth (delegera till Auth0):**
- För: Outsourca komplexitet
- Emot: Vendor lock-in, $23/månad minimum, användare kan inte äga sina data
## Konsekvenser
**För:**
- Stateless (vilken server kan validera token)
- Fungerar för webb + mobil
- Inget delat sessionlager
**Emot:**
- Kan inte återkalla tokens före utgång (mitigering: håll utgång kort)
- Något större payload än session-ID:n
ADR-011: Deploya till AWS vs GCP
# ADR-011 — Deploya infrastruktur till AWS
**Datum:** 2026-03-01
**Status:** Godkänd
## Kontext
Behöver molnhosting för produktionsapp. Måste stödja: containerorkestration, hanterad DB, CDN, övervakning.
## Beslut
Använd **AWS** (ECS Fargate + RDS + CloudFront).
## Alternativ
**Google Cloud Platform:**
- För: Bättre Kubernetes (GKE), billigare egress
- Emot: Teamet har ingen GCP-erfarenhet (träningskostnad)
**Själv-hostad (DigitalOcean):**
- För: Billigare ($20/månad vs $200/månad)
- Emot: Inget team för att hantera infra, single point of failure
## Konsekvenser
**För:**
- Teamet känner AWS (snabbare installation, färre misstag)
- Moget ekosystem (Fargate = inga servrar att hantera)
- CloudFront CDN inbyggd
**Emot:**
- Högre kostnad än GCP/DO (~$200/månad)
- Vendor lock-in (skulle ta veckor att migrera)
ADR-015: Monorepo vs multi-repo
# ADR-015 — Använd monorepo för frontend + backend
**Datum:** 2026-03-10
**Status:** Godkänd
## Kontext
Vi har en React-frontend och Node.js-backend. De delar TypeScript-typer. Behöver versioneringsstrategi.
## Beslut
Använd **monorepo** (pnpm workspaces) med delade paket.
## Alternativ
**Multi-repo (separata repon för FE/BE):**
- För: Oberoende versioning, tydliga gränser
- Emot: Typ-synk-smärta, duplicerad verktygskonfigurering, svårare att koordinera ändringar
**Separata repon + publicerat typpaket:**
- För: Typer stannar synkade via npm
- Emot: Extra publishsteg, versioneringskomplexitet
## Konsekvenser
**För:**
- Delade typer direkt importerade (inget publishsteg)
- Enda CI/CD-pipeline
- Atomiska commits över FE/BE
**Emot:**
- Större repo klonstorlek
- Kräver workspace-medvetna verktyg (pnpm/nx)
Prova själv
Tänk på det senaste stora tekniska beslutet du fattade. Skriv en ADR:
- Kontext: Vilket problem löste du?
- Beslut: Vad valde du?
- Alternativ: Vad annat övervägde du?
- Konsekvenser: Vilka är för-, nackdelar?
Ställ in en timer på 10 minuter. Skriv den. Du har nu ett beslut bevarat för framtida dig (och ditt team).
Nästa gång någon frågar “Varför valde vi X?” svarar du: “Se ADR-XXX.”
Ingen mer förlorad kontext. Ingen mer omförhandling. Inget mer “Jag tror Sarah nämnde något om…?”
Bara tydliga, dokumenterade beslut som sparar tid och förhindrar minnesförlust.
Kommer i Del 6: Kopiera denna mall och skeppa snabbare — Kom igång på 5 steg: kopiera mallen, generera en TRD, fyll i canvas, skapa din plan, och starta din första session. Plus: kommandoreferens, vanliga installationsmisstag och FAQ.
Nyckelord: architecture decision records, ADR, teknisk dokumentation, beslutsdokumentation, mjukvaruarkitektur, teamkunskapshantering