Beslutsprotokoll för AI-driven mjukvaruutveckling

Beslutsprotokoll är den saknas minneslagret i AI-assisterad mjukvaruutveckling. De fångar inte bara vad som byggdes, utan varför — och den skillnaden blir avgörande när AI-verktyg skriver din kod.

Beslutsprotokoll är det saknas minneslagret

AI-drivet programmering förändrar ekonomin i mjukvaruutveckling genom att göra kod billigare att generera, enklare att refactora och snabbare att kasta bort. Det är användbart. Det är också farligt, eftersom när koden blir lättare att producera är den knappa resursen inte längre skrivning — den knappa resursen är bedömningsförmåga.

Varför valde teamet PostgreSQL istället för DynamoDB? Varför kräver produkten human review innan AI-genererade e-postmeddelanden skickas? Varför visar gränssnittet förslag i en sidopanel istället för att tillämpa dem direkt? Varför avvisades en enklare approach för sex månader sedan? Koden kan visa vad som finns, men den förklarar sällan varför det finns.

Beslutsprotokoll löser detta problem genom att tillhandahålla ett kort, versionskontrollerat dokument som fångar ett viktigt val, kontexten bakom det, de alternativ som övervägdes och de konsekvenser som teamet accepterade. I en AI-assisterad kodbas blir dessa protokoll mer än dokumentation — de blir ett hållbart projektmindre som både människor och AI-kodagenter kan läsa innan de gör framtida ändringar. Den praktiska arbetsregeln är enkel: håll beslutsprotokoll som Markdown-filer i arkivet, granska dem som kod och låt framtida AI-verktyg läsa dem innan de föreslår eller implementerar ändringar.

Vad är beslutsprotokoll?

Ett beslutsprotokoll är en skriftlig post av ett meningsfullt beslut, strukturerat för att svara på fyra grundläggande frågor: vad beslöt vi, varför beslöt vi det, vilka alternativ övervägde vi och vilka konsekvenser accepterade vi? Den vanligaste formen är Architecture Decision Record, förkortat ADR. ADR:er används flitigt för att dokumentera tekniska beslut, och samma mönster kan utvidgas bortom arkitektur till produkt- och designarbete.

För AI-drivet programmering är tre typer särskilt användbara:

Tillsammans beskriver ADR:er, PDR:er och DDR:er inte bara systemets struktur utan även produktens intention och resonemanget bakom användarupplevelsen. Den kombinationen är viktig eftersom AI-agenter kan läsa kod, men kod ensam innehåller inte tillräcklig kontext för att fatta goda beslut. Beslutsprotokoll ger AI-system en granskad, hållbar, humana godkänd källa till projektintention.

Arkitekturbeslutsprotokoll (ADR)

Arkitekturbeslutsprotokoll fångar tekniska och strukturella beslut. Använd en ADR när ett beslut påverkar systemets utformning — dess gränser, beroenden, operativa modell eller långsiktig underhållbarhet.

Exempel på beslut som är värda att protokollera som ADR:er inkluderar:

• Att välja PostgreSQL som primär databas
• Att använda en evenemangsdriven arkitektur för bakgrundsbearbetning
• Att behålla applikationen som en modulär monolit
• Att införa en kö för meddelanden
• Att välja REST istället för GraphQL
• Att använda server-side rendering för webbapplikationen
• Att kräva att alla bakgrundsjobb är idempotent
• Att anta en specifik autentiserings- och auktoriseringsmodell

En ADR är inte ett fullständigt arkitekturdokument — den är avsiktligt liten och registrerar ett viktigt beslut vid en specifik tidpunkt. En bra ADR förhindrar arkitektonisk amnesi: utan den kan framtida medverkande återupptäcka samma avvägningar, återöppna gamla debatter eller oavsiktligt återvända viktiga begränsningar.

I AI-drivet programmering har ADR:er ännu mer tyngd. AI-verktyg är ofta skickliga på lokal optimering och kan föreslå en tekniskt plausibel ändring som strider mot en större arkitektonisk begränsning. En ADR ger AI:n en tydlig gräns: “Så här ska detta system vara utformat.”

Produktbeslutsprotokoll (PDR)

Produktbeslutsprotokoll fångar produktbeteende, omfattning och användarriktad intention. Detta är mindre vanligt än ADR:er, men det är ofta lika värdefullt — produktbeslut sprids ofta över tickets, roadmap-verktyg, chatttrådar, mötesanteckningar och människors minnen, vilket gör dem lätta att glömma för människor och nästan omöjliga för AI-verktyg att pålitligt härleda.

Använd en PDR när ett beslut påverkar vad produkten gör, vem den tjänar, vad som avsiktligt är utanför omfattningen eller hur en användarriktad funktion bör bete sig. Exempel inkluderar:

• AI-genererade meddelanden måste förbli utkast tills de granskas av en människa
• Användare på fri nivå kan skapa upp till tre projekt
• Raderade arbetsplatser är återställbara i 30 dagar
• Team-fakturering är utanför omfattningen för version 1
• Användare kan exportera sina data utan att kontakta supporten
• AI-sammanfattningar med låg konfidens visar en varning istället för att döljas

En PDR är särskilt användbar när ett produktval verkar godtyckligt ur koden. Koden kan innehålla en gräns på tre projekt för fria användare, och utan en PDR kan ett AI-verktyg behandla det numret som en magisk konstant och föreslå att ändra det. Med en PDR kan AI:n se att gränsen är kopplad till prissättningsstrategi, onboardingskostnad eller supportbelastning — och att ändra det kräver ett medvetet produktbeslut, inte en snabb redigering.

Designbeslutsprotokoll (DDR)

Designbeslutsprotokoll fångar användarupplevelse, interaktion, visuell och content-designbeslut. Använd en DDR när ett beslut påverkar hur användare interagerar med produkten, hur information presenteras eller hur ett designprincip bör tillämpas i framtida arbete.

Exempel på designbeslut som är värda att protokollera inkluderar:

• Använd inline-validering istället för validering endast vid inlämning
• Placera AI-förslag i en sidopanel istället för direkt i editorn
• Använd progressiv avslöjande för avancerade inställningar
• Kräv bekräftelse innan destruktiva åtgärder
• Använd “Utkast” och “Publicerad” istället för “Inaktiv” och “Aktiv”
• Håll primära åtgärder synliga på mobila skärmar

Designintention är lätt att förlora under implementation. En utvecklare kan förenkla en flöde, eller en AI-agent kan generera en komponent som tekniskt fungerar men bryter mot den avsedda interaktionsmodellen. Till exempel kan en DDR protokollera: “Vi visar AI-skrivförslag bredvid dokumentet, inte inuti det, eftersom användare behöver jämföra genererad text med sitt eget utkast innan de accepterar ändringar.” Det protokoll ger framtida medverkande en princip att bevara, inte bara en layout att kopiera.

Varför beslutsprotokoll betyder mer med AI

AI-kodverktyg är kraftfulla, men de är ofta stateless eller bara delvis medvetna om projektets historia. De kan inspektera filer, härleda mönster och generera ändringar — men de vet inte automatiskt vilka beslut är avsiktliga, vilka är oavsiktliga och vilka redan har debatterats och lösts. Detta skapar flera distinkta risker.

AI kan återöppna avgjorda debatter

Om teamet redan har beslutat att använda en modulär monolit, kan en AI-agent fortfarande föreslå att extrahera en tjänst eftersom det ser rent ut i isolering. Utan en ADR har AI:n inget hållbart sätt att veta att teamet redan har övervägt och avvisat den vägen, och resultatet är slöseri med arbete eller en subtil regression i systemkoherens.

AI kan optimera lokalt och skada globalt

En genererad refactor kan göra en fil renare medan den strider mot systemgränser. En UI-ändring kan minska komponentkomplexiteten medan den svagar den avsedda användarupplevelsen. En produktändring kan förenkla implementationen medan den bryter mot prissättnings- eller efterlevnadsantaganden. Beslutsprotokoll ger AI:n en större referensram innan den agerar på snävt omfattningsmässiga signaler.

AI kan bevara kod men förlora intention

En modell kan följa befintliga mönster i kodbasen, men mönster är inte detsamma som principer. Ibland är befintlig kod en kompromiss. Ibland är den övergående. Ibland finns den på grund av en extern begränsning som inte är synlig i filen. Beslutsprotokoll förklarar skillnaden mellan “så här fungerar det” och “så här är det byggt på detta sätt.”

AI kan generera plausibla men felaktiga resonemang

AI kan utkast beslutsprotokoll, men den kan också uppfinna självsärliga förklaringar som inte stämmer överens med det verkliga beslutet. Det är därför human review är oundvikligt: AI kan generera utkastet till ett protokoll, men en människa måste verifiera att det korrekt beskriver det faktiska beslutet, alternativen och konsekvenserna innan protokollsammanslagningen sker.

Beslutsprotokoll som del av en bredare metodologi

Beslutsprotokoll är inte bara dokumentation — de är en del av ett bredare arbetssätt som ligger i skärningspunkten mellan lättviktig arkitekturstyrning, docs as code, AI-augmenterade kunskapsförvaltningsarbetsflöden, produktupptäckt, designrationell, AI-styrning och kodgranskning. Ett användbart sätt att beskriva den större processen är Decision-Oriented Development.

De flesta AI-drivna programmeringsarbetsflöden fokuserar snävt på generate-review-commit-loopen:

Den cykeln är för tunn för seriös systemsarbete. Ett starkare arbetsflöde behandlar arkivet som en lagring av både kod och intention — diagrammen här använder Mermaid, ett lättviktigt format som fungerar bra inuti Markdown-beslutsprotokoll också:

Denna process förvandlar arkivet till mer än en kodlagring. Det blir källan till sanning för implementation, intention och resonemang — ett hållbart artefakt som ackumulerar värde med varje beslut som fattas.

Beslutsprotokoll och docs as code

Beslutsprotokoll fungerar bäst när de följer docs-as-code-principer, vilket innebär att de bör lagras i samma arkiv som koden, skrivas i ren Markdown, granskas i pull requests, versionskontrolleras med Git, länkas till relaterade issues och pull requests, och vara sökbara av både människor och AI-verktyg. Detta är mycket mer pålitligt än att lagra viktiga beslut i chatt, wikisidor, presentationer eller mötesanteckningar — de verktygen kan fortfarande vara användbara för diskussion, men det accepterade beslutet ska alltid leva nära koden.

En välorganiserad arkivstruktur för beslutsprotokoll kan se ut så här:

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

För mindre projekt fungerar en plattare struktur lika bra. Den exakta mapporganisationen är mindre viktig än konsistens — protokollen måste vara lätta att hitta, lätta att granska och lätta för AI-verktyg att ladda som kontext innan de agerar på kodbasen. För Go-team passar denna docs/decisions/-struktur naturligt bredvid cmd/, internal/ och api/-layouten som beskrivs i Go Project Structure: Practices & Patterns, som rekommenderar docs/ som hem för arkitekturbeslut och API-referenser.

Ett praktiskt mall för beslutsprotokoll

En användbar mall för beslutsprotokoll bör vara tillräckligt kort så att människor faktiskt använder den. Här är en praktisk Markdown-mall som inkluderar ett valfritt men värdefullt AI-guidance-avsnitt:

# Beslut: Kort titel

Status: Föreslagen | Accepterad | Överträdd | Deprecierad
Datum: ÅÅÅÅ-MM-DD
Typ: Arkitektur | Produkt | Design
Ägare: Team eller namn

## Kontext

Beskriv problemet, begränsningar, mål, användarbehov, tekniska fakta,
och affärsfaktorer som ledde till detta beslut.

## Beslut

Uppge beslutet tydligt.

## Alternativ som övervägts

### Alternativ 1

Fördelar:
- ...

Nackdelar:
- ...

## Konsekvenser

Beskriv vad som blir enklare, vad som blir svårare, och vilka risker
eller uppföljararbete detta skapar.

## AI-guidance

När en AI-assistent arbetar i detta område bör den:
- Bevara ...
- Undvika ...
- Föredra ...
- Be om granskning när ...

## Länkar

- Relaterade issues:
- Relaterade pull requests:
- Relaterade filer:
- Överträder:
- Överträdd av:

Avsnittet “AI-guidance” är valfritt, men för AI-drivet programmering är det extremt värdefullt — det förvandlar beslutsprotokollet till en hållbar instruktion för framtida agenter som arbetar i samma del av kodbasen.

Vad ska ingå i ett beslutsprotokoll?

Inte varje val förtjänar ett protokoll, och om varje liten implementeringsdetalj blir ett beslutsprot kollapsar processen i brus. Skapa ett beslutsprotokoll när ett val är meningsfullt och sannolikt att betyda något senare.

Bra kandidater är beslut som:

• Påverkar flera delar av systemet
• Kodar en produktlöfte
• Löser en verklig debatt
• Inför en långsiktig avvägning
• Beror på affärs-, efterlevnads- eller operativa begränsningar
• Vore dyrt att återupptäcka senare
• Framtida AI-verktyg rimligt kan få fel
• Framtida medverkande kan vara frestade att återvända lättvint

Dåliga kandidater inkluderar små refactor-val, uppenbara bug-fixes, tillfälliga experiment, lokala namngivningsbeslut och implementeringsdetaljer utan varaktig konsekvens. En bra tumregel är enkel: om att återvända beslutet kräver diskussion, protokollera beslutet.

Statusvärden och livscykel

Beslutsprotokoll bör ha en livscykel för att signalera deras nuvarande ställning. De enklaste statusvärdena är tillräckliga.

Föreslagen — Beslutet övervägs men är inte ännu accepterat. Använd detta när teamet vill diskutera ett beslut i en pull request innan de förbinder sig till det.

Accepterad — Beslutet är aktivt och bör leda framtida arbete. De flesta användbara beslutsprotokoll kommer att tillbringa mest delen av sitt liv i detta tillstånd.

Överträdd — Beslutet har ersatts av ett nyare protokoll. Ta inte bort gamla protokoll; behåll dem för historikens skull och länka till det nyare beslutet så att evolutionen av tänkandet förblir synlig.

Deprecierad — Beslutet rekommenderas inte längre men kan fortfarande beskriva befintliga delar av systemet. Detta är särskilt användbart under migrationer, när gamla mönster finns i kodbasen bredvid nyare tillvägagångssätt.

Den viktiga principen är att beslutsprotokoll bör vara append-friendly. När teamet ändrar riktning, skapa ett nytt protokoll och länka det gamla snarare än att skriva om historien för att få det att se renare ut.

Hur AI bör generera beslutsprotokoll

AI kan hjälpa till att skapa beslutsprotokoll, och detta är en av de bättre användningarna av AI i mjukvaruutveckling — den är snabb på att utkast strukturerade dokument från kontext. Efter en diskussion, arkitekturganskning eller pull request kan du be en AI-assistent att utkast ett protokoll:

Utkasta ett Arkitekturbeslutsprotokoll för beslutet i denna pull request.
Inkludera kontext, alternativ, konsekvenser och AI-guidance.
Spara det som Markdown under docs/decisions/architecture.

För produktarbete:

Utkasta ett Produktbeslutsprotokoll som förklarar varför AI-genererade meddelanden
måste förbli utkast tills de granskas av användaren.
Inkludera användarpåverkan, out-of-scope-beteende, avvägningar och AI-guidance.

Det AI-genererade protokollet ska dock inte lita på automatiskt. Human review bör verifiera att kontexten är korrekt, att AI inte har uppfunnit resonemang, att de listade alternativen är verkliga, att konsekvenserna är ärliga, och att AI-guidance stämmer överens med teamets faktiska intention. AI är en utkastassistent — den är inte ägaren till beslutet.

Hur AI bör läsa beslutsprotokoll

Den andra halvan av praktiken är att instruera AI att läsa protokollen innan den agerar. Innan du ber en AI-assistent att implementera en ändring, inkludera en instruktion som denna:

Innan du modifierar denna funktion, läs docs/decisions.
Identifiera några Arkitektur-, Produkt- eller Designbeslutsprotokoll som gäller.
Följ accepterade beslut. Om din föreslagna ändring strider mot ett beslutsprotokoll,
förklara konflikten innan du ändrar kod.

För större uppgifter, förstärk rollen för protokollen som projektmindre:

Använd beslutsprotokollen som projektmindre.
Återvänd inte accepterade beslut utan att föreslå ett nytt överträdande beslut.
När du genererar kod, förklara vilka beslutsprotokoll påverkade implementationen.

Detta förändrar AI:s roll från “förutsäg plausibel kod” till “operera inuti ett dokumenterat system av begränsningar” — en betydande förbättring i pålitlighet för komplexa eller långlivade projekt.

Beslutsprotokoll i pull requests

Beslutsprotokoll bör vara en del av normal pull request-granskning snarare än en separat process. En enkel PR-checklista-post gör vanligheten synlig:

## Checklista för beslutsprotokoll

- [ ] Denna PR introducerar inte ett betydande arkitektur-, produkt- eller designbeslut.
- [ ] Denna PR introducerar ett betydande beslut och inkluderar ett nytt beslutsprotokoll.
- [ ] Denna PR ändrar ett tidigare beslut och inkluderar ett överträdande protokoll.
- [ ] Relevanta befintliga beslutsprotokoll har övervägts.
- [ ] AI-genererad kod följer de accepterade beslutsprotokollen.
- [ ] AI-generade beslutsprotokoll har granskats av en människa.

Den här checklisten är enkel, men den förändrar beteende genom att påminna teamet att kod inte är det enda artefaktet som betyder något i en pull request. Den gör det också naturligt att fånga när en AI-generad ändring tyst strider mot ett tidigare beslut.

Beslutsprotokoll och arkitekturstyrning

Traditionell arkitekturstyrning misslyckas ofta eftersom den är för tung, för långsam eller för frånkopplad från implementation — centrala godkännandepaneler, stora förhandsdokument och gatekeeping-processer som blockerar snarare än leder. Beslutsprotokoll erbjuder ett lättare alternativ som integreras direkt i arbetsflödet.

De kräver inte en central arkitekturpanel för varje ändring, och de blockerar inte team från att lära sig och anpassa sig. Istället skapar de en spår av beslut som kan granskas, refereras och byggas på över tid. Detta stödjer evolutionär arkitektur: arkitekturen kan ändras, men den ändras med minne snarare än trots det. Teamet kan besöka gamla beslut utan att behöva återupptäcka varför de gjordes, vilket är en hälsosammare och ärligare form av styrning:

• Små protokoll istället för jättedokument
• Granskning nära koden istället för separat godkännandeteater
• Historisk kontext istället för tribalkunskap
• Explicita avvägningar istället för dolda antaganden

Beslutsprotokoll och produktledning

Produktarbete behöver också beslutsminne, och detta är ett område där värdet av beslutsprotokoll ofta underskattas. En roadmap säger vad som kan hända. En ticket säger vad som ska byggas näst. Analytik säger vad användare gjorde. Ingen av dessa förklarar fullt ut varför ett produktbeteende finns.

Produktbeslutsprotokoll fyller det gapet och är särskilt användbara för prissättnings- och packningsbeslut, behörighetsmodeller, gränser och kvoter, AI-säkerhet och review-flöden, onboardingsval, användarrolldefinitioner, samarbetsregler, datalagringspolicyer och funktionsofattning. När de implementeras blir produktbeslut osynliga i koden — senare ser någon bara koden och frågar: “Varför fungerar det på detta sätt?” En PDR ger svaret i en form som både människor och AI-verktyg kan hitta och använda.

Beslutsprotokoll och designsystem

Designsystem dokumenterar ofta komponenter, tokens och användningsregler, men de dokumenterar sällan varför systemet fungerar på det sättet. Designbeslutsprotokoll fyller det gapet. En komponentbibliotek kan säga “använd bekräftelsedialogen för destruktiva åtgärder”, medan en DDR förklarar resonemanget: “Vi kräver bekräftelse för destruktiva åtgärder eftersom användare ofta arbetar med delat teamdata, och oavsiktlig radering har en hög återställningskostnad.”

Det resonemanget betyder mer än den specifika komponenten. Det hjälper framtida designers, utvecklare och AI-verktyg att tillämpa principen korrekt i nya situationer. Utan DDR:n kan en AI-agent generera en snabbare interaktion som hoppar över bekräftelse eftersom den verkar mer effektiv. Med DDR:n kan agenten känna igen att att bevara säkerhetsegenskapen är avsiktligt och oundvikligt.

Hur beslutsprotokoll stödjer spec-driven utveckling

Spec-driven utveckling förklarar vad systemet ska göra. Beslutsprotokoll förklarar varför teamet valde den riktningen, och skillnaden betyder betydligt för AI-assisterat arbete.

En funktionsspecifikation kan säga att AI-genererade e-postmeddelanden måste sparas som utkast. Ett Produktbeslutsprotokoll förklarar varför automatisk sändning avvisades, vilka risker som övervägdes, och vilka framtida ändringar som kräver ett nytt beslut. En designspecifikation kan beskriva en sidopanelinteraktion, medan den motsvarande DDR:n förklarar varför inline-AI-redigeringar explicit avvisades och varför att bevara användarkontroll vägdes tyngre än arbetsflödeshastighet. En arkitekturspecifikation kan definiera en tjänstegräns, och dess ADR förklarar varför teamet valde den gränsen framför en enklare eller mer distribuerad alternativ.

Specen leder implementationen. Beslutsprotokollet bevarar bedömningsförmågan. Tillsammans ger de AI-kodagenter både instruktioner och kontext — “vad” och “varför” — vilket är det som gör kombinationen så effektiv för komplexa, långlivade system.

Beslutsprotokoll är inte specifikationer

Beslutsprotokoll är relaterade till specifikationer, men de tjänar ett annat syfte. En specifikation säger “systemet ska göra X”, medan ett beslutsprotokoll säger “vi valde X istället för Y på grund av dessa begränsningar och avvägningar.” Den “istället för Y”-delen är den värdefulla delen. AI-verktyg genererar ofta lösningar genom att hitta en plausibel väg till det begärda resultatet, men beslutsprotokoll berättar för dem vilka plausibla vägar som redan har utforskats, utvärderats och avvisats — vilket minskar churn och förbättrar kvaliteten på AI-assisterat arbete.

Beslutsprotokoll är inte ett ersättande för tester

Tester verifierar beteende; beslutsprotokoll förklarar intention. Båda är nödvändiga och de arbetar tillsammans. En test kan säkra att AI-generade e-postmeddelanden måste sparas som utkast, medan ett Produktbeslutsprotokoll förklarar att detta krävs eftersom användare måste granska AI-generad kommunikation innan den lämnar systemet. Testet skyddar beteendet. Beslutsprotokollet skyddar betydelsen. Tillsammans gör de framtida ändringar säkrare och mer förutsägbara.

Beslutsprotokoll är inte ett ersättande för kodkommentarer

Kodkommentarer förklarar lokala implementeringsdetaljer, medan beslutsprotokoll förklarar bredare beslut. Använd kommentarer för överraskande rader, randfall, workarounds och funktioner som inte kan förenklas. Använd beslutsprotokoll för varför en arkitektur finns, varför ett produktbeteende finns, varför ett interaktionsmönster finns, och varför teamet valde en riktning framför en annan. Om förklaringen endast påverkar några rader, är en kommenter rätt verktyg. Om den påverkar systemets riktning, är ett beslutsprotokoll rätt verktyg.

Vanliga misstag

Att skriva protokoll för sent

Ett beslutsprotokoll bör skrivas när beslutet fattas, inte månader senare när alla har glömt avvägningarna. Det är bra att utkast ett under en pull request. Det är ännu bättre att utkast det innan implementation, medan beslutet fortfarande aktivt diskuteras och alternativen är färska.

Att göra protokoll för långa

Ett beslutsprotokoll är inte en essay. Det bör vara detaljerat nog för att bevara bedömningsförmågan men kort nog så att människor faktiskt läser det. Föredra tydlighet framför komplettitet — ett koncist protokoll som läses är mycket mer värdefullt än ett omfattande som hoppas över.

Att protokollera beslut utan konsekvenser

Konsekvensavsnittet är hjärtat i protokollet. Ett beslut utan angivna konsekvenser är ofta bara en preferens snarare än ett verkligt beslut. Bra protokoll erkänner avvägningar ärligt, inklusive vad som blir svårare eller riskfylld som ett resultat av valet.

Att redigera gamla protokoll som om historien ändrades

När ett beslut ändras, skapa ett nytt protokoll och markera det gamla som överträdd. Att tyst skriva om ett gammalt beslut för att matcha det nuvarande tillståndet förstör den historiska kontexten som gör beslutsprotokoll värdefulla. Historien är användbar just för att den visar hur tänkandet utvecklades.

Att låta AI-generade protokoll slås samman utan granskning

AI kan producera ett polerat, välstrukturerat protokoll som är subtilt felaktigt. Behandla AI-generade beslutsprotokoll exakt som AI-generad kod — granska dem noggrant, verifiera att resonemanget är korrekt, och se till att konsekvensavsnittet speglar vad teamet faktiskt accepterade.

Att dölja protokoll utanför arkivet

Om beslutsprotokoll lever i en separat wiki eller dokumentationssystem, är de mindre sannolika att uppdateras tillsammans med kodändringar och mycket mindre sannolika att läsas av AI-kodverktyg som laddar kontext för en uppgift. Att behålla dem i arkivet är inte bara en bekvämlighet — det är det som gör praktiken fungerande för AI-assisterad utveckling.

En lättviktig operativ modell

En praktisk teamprocess som lägger till minimal overhead ser ut så här:

1. Under planering eller implementation, identifiera om ett meningsfullt beslut fattas.
2. Be en AI-assistent att utkast en ADR, PDR eller DDR baserat på diskussionen.
3. Granska utkastet som team, verifiera kontext, alternativ och konsekvenser.
4. Commit protokollet som Markdown i arkivet.
5. Länka det från det relaterade issue eller pull request.
6. Instruera AI-kodverktyg att läsa relevanta protokoll innan framtida ändringar görs i området.
7. Överträd protokoll när beslut ändras, bevara det gamla protokollet för historikens skull.

Detta kräver inte en ny byråkrati eller en dedikerad dokumentationsroll. Det kräver en liten vana: att bevara viktig bedömningsförmåga i ögonblicket den skapas, nära koden där den kommer att behövas.

Exempel ADR

# Beslut: Använd PostgreSQL för primär applikationslagring

Status: Accepterad
Datum: 2026-06-25
Typ: Arkitektur
Ägare: Plattformsteamet

## Kontext

Applikationen behöver hållbar relationell lagring för konton, projekt,
behörigheter och audit-händelser. Teamet förväntar sig frekventa rapportfrågor
och starka konsistenskrav för behörighetskontroller.

## Beslut

Vi kommer att använda PostgreSQL som primär applikationsdatabas.

## Alternativ som övervägts

### DynamoDB

Fördelar:
- Operationellt skalbar
- Bra passform för förutsägbara key-value-åtkomstmönster

Nackdelar:
- Mer komplex för relationella frågor
- Svårare för ad hoc-rapportering
- Mindre bekant för det nuvarande teamet

### MySQL

Fördelar:
- Mörd relationell databas
- Bekant operativ modell

Nackdelar:
- PostgreSQL matchar teamets behov bättre för JSON-stöd,
  indexeringsalternativ och befintlig expertis

## Konsekvenser

PostgreSQL blir en kärnoperativ beroende. Teamet måste hantera
migrationer noggrant och övervaka frågoprestanda. I gengäld får
applikationen stark relationell modellering, mognad indexerings och
flexibelt rapportstöd.

## AI-guidance

När du modifierar persistenskod, föredra relationell modellering i PostgreSQL.
Inför inte en andra primär databas utan en överträdande ADR.

Exempel PDR

# Beslut: AI-genererade e-postmeddelanden måste förbli utkast

Status: Accepterad
Datum: 2026-06-25
Typ: Produkt
Ägare: Produktteamet

## Kontext

Produkten kan generera e-postsvar med AI. Att skicka e-post är en
hög-trust-åtgärd eftersom misstag kan nå kunder, partners eller
intern team.

## Beslut

AI-genererade e-postmeddelanden måste skapas som utkast. En human användare måste
granska och skicka dem.

## Alternativ som övervägts

### Skicka automatiskt

Fördelar:
- Snabbare arbetsflöde
- Mindre användaransträngning

Nackdelar:
- Högre risk för felaktiga eller olämpliga meddelanden
- Lägre användartrust
- Svårare att återhämta sig från misstag

### Be om bekräftelse endast efter generation

Fördelar:
- Behåller arbetsflödet enkelt
- Ger viss användarkontroll

Nackdelar:
- Uppmuntrar fortfarande ytlig granskning
- Passar inte befintlig e-postklientbeteende lika bra som utkast

## Konsekvenser

Arbetsflödet är något långsammare, men säkrare och mer pålitligt.
Framtida automatisering kan förbättra granskningshastigheten, men får inte kringgå
human godkännande utan en överträdande PDR.

## AI-guidance

När du bygger e-postgenereringsfunktioner, skapa utkast som standard.
Lägg inte till automatisk sändning om inte en ny accepterad PDR explicit tillåter det.

Exempel DDR

# Beslut: Visa AI-skrivförslag i en sidopanel

Status: Accepterad
Datum: 2026-06-25
Typ: Design
Ägare: Designteamet

## Kontext

Användare behöver hjälp med att förbättra skriftlig innehåll, men de behöver också
behålla kontrollen över sluttexten. Inline-AI-redigeringar kan göra det svårt att
skilja användarskrivet innehåll från genererade förslag.

## Beslut

AI-skrivförslag kommer att visas i en sidopanel. Användare kan acceptera,
avvisa eller kopiera förslag till huvudeditorn.

## Alternativ som övervägts

### Tillämpa förslag inline

Fördelar:
- Snabbt
- Känns integrerat

Nackdelar:
- suddar ut författarskap
- Gör granskning svårare
- Kan överraska användare

### Visa förslag i en modal

Fördelar:
- Fokuserad upplevelse
- Enkel att implementera

Nackdelar:
- Avbryter skrivflödet
- Svårare att jämföra förslag och originaltext

## Konsekvenser

Sidopaneln tar mer skärmyta, särskilt på små skärmar.
Däremot bevarar den användarkontroll och gör granskning tydligare.

## AI-guidance

När du lägger till skrivassisteringsfunktioner, bevara separation mellan
användartext och AI-förslag. Tillämpa inte genererad text direkt
i dokumentet utan explicit användaråtgärd.

Föreslagen promptbibliotek

Använd dessa prompts för att göra beslutsprotokoll en del av daglig AI-assisterad utveckling.

Hitta relevanta protokoll innan du arbetar på en funktion:

Läs docs/decisions och identifiera några accepterade beslutsprotokoll som gäller
för denna uppgift. Sammanfatta begränsningarna innan du föreslår kodändringar.

Utkasta en ny ADR:

Utkasta ett Arkitekturbeslutsprotokoll för detta tekniska beslut.
Inkludera kontext, beslut, alternativ, konsekvenser och AI-guidance.
Håll det koncist och specifikt.

Utkasta en ny PDR:

Utkasta ett Produktbeslutsprotokoll för detta produktbeteende.
Inkludera användarpåverkan, omfattning, alternativ, konsekvenser och AI-guidance.

Utkasta en ny DDR:

Utkasta ett Designbeslutsprotokoll för detta interaktionsmönster.
Inkludera användarproblem, alternativ, avvägningar, konsekvenser och AI-guidance.

Granska en pull request mot befintliga beslut:

Granska denna pull request mot de accepterade beslutsprotokollen i docs/decisions.
Identifiera några konflikter, saknade beslutsprotokoll eller beslut som bör
överträdas.

Överträd ett beslut:

Skapa ett nytt beslutsprotokoll som överträder det befintliga.
Bevara den historiska rationellen, förklara vad som ändrades, och länka båda protokollen.

Relaterad läsning

• Michael Nygard’s originala ADR-format — den grundläggande inlägget som startade ADR-rörelsen
• ADR GitHub-organisation — verktyg, mallar och communityresurser för att hantera beslutsprotokoll
• Vad är Spec-Driven Development? Specen som källa till sanning — den kanoniska SDD-definitionen som förklarar hur funktionsspecar kompletterar beslutsprotokoll: båda gör intention hållbar, på olika nivåer av systemet
• Spec-Driven Development vs Vibe Coding: Waterfall? — när man ska använda SDD och när man ska stanna med snabbare, lösare arbetsflöden
• App-arkitektur i produktion: Integrationsmönster, koddesign och dataåtkomst — klusterhemmet som täcker integration, testning, dataåtkomst och mjukvardokumentationsmönster
• AI för kunskapsförvaltning: Verkliga arbetsflöden som håller — praktiska AI-augmenterade kunskapsflöden som kompletterar beslutsprotokollpraktiken