Hur man delar kunskap med en AI – och med varandra
Det mest underskattade med att jobba med AI-agenter är inte vilken modell man väljer. Det är vad agenten får veta.
En agent vet det som står i dess kontext. Inget mer. Den minns inte förra veckans diskussion, vet inte varför ni valde Postgres och har ingen aning om att kunden alltid vill ha summor exklusive moms. Precis som en ny kollega första dagen.
Skillnaden är att den nya kollegan kan fråga runt. Agenten gör det som står – eller gissar.
Samma underlag för alla
Vi har slutat skriva dokumentation "för människor" och "för AI" var för sig. Det är samma underlag. Det som hjälper en agent att göra rätt hjälper också en ny utvecklare, en projektledare eller oss själva om ett år.
Dokumentationen blir av – den skrivs och underhålls löpande, ofta av agenten själv.
Fyra lager
Arbetsbeskrivningen. En fil i roten av projektet – CLAUDE.md eller den verktygsneutrala AGENTS.md – som beskriver hur man jobbar här: kommandon, konventioner, regler och var allt annat finns. Den är kort, och den växer av en enkel regel: gör agenten samma misstag två gånger blir det en rad.
Beslutsloggen. Korta dokument om varför vi valde som vi gjorde, och vilka alternativ vi valde bort. Utan dem föreslår agenten gärna just det vi redan förkastat – med goda argument.
Planen. För varje större förändring: omfattning, steg, acceptanskriterier, risker och hur varje steg verifieras. Planen är kontraktet mellan människa och agent. Vi granskar planen, agenten bygger efter den.
Koden och testerna. Facit. Oavsett vad som står i dokumenten är det testerna som avgör om det blev rätt.
Några regler vi lärt oss
- Skriv kort. En plan eller ett beslut säger vad som gäller och varför – en gång. Långa dokument läses inte, varken av människor eller agenter.
- Ett ställe per sanning. Länka hellre än att upprepa. Två kopior av samma regel glider isär.
- Skriv mönster först när de upprepas. Har samma sak lösts på samma sätt två gånger är det ett mönster. Innan dess är det en gissning.
- Lägg till, skriv inte om. Upptäcker man något under arbetet som ändrar planen blir det en notering längst ner. Då går det att se vad man trodde och vad man lärde sig.
- Låt agenten underhålla. Att hålla dokumentationen aktuell var förr det som aldrig blev av. Nu är det en del av varje ändring.
Vad det ger
I en omfattande ombyggnad vi nyligen gjorde låg 29 dokumenterade arkitekturbeslut och drygt 50 planfiler bakom koden. Det låter mycket. Men varje fil är kort, och tillsammans gjorde de att två utvecklare med agenter kunde hålla ett högt tempo i månader utan att tappa bort varför saker var som de var.
Den största vinsten är kanske den minst uppenbara: kunskapen sitter inte längre i huvudet på den som skrev koden. Den finns där nästa person – eller nästa agent – letar.
Dokumentationen var förr det som aldrig blev av. Nu blir den av – för att den behövs varje dag.
Utanför koden
Samma princip gäller när AI ska hjälpa till i verksamheten, inte bara i koden. Kunskapen om hur ni räknar, vad begreppen betyder och vilka undantag som gäller behöver skrivas ner någonstans där assistenten når den. Om hur AI får tillgång till er data.
Vill ni se hur vi strukturerar ett projekt i praktiken? Hör av er.