När dokumentation förvandlas till ett arkiv av förbisedd kunskap

Tänk dig följande: du börjar ett nytt projekt med en ren CLAUDE.md-fil. Några användbara tips ramlar in. Några kontextanteckningar. En varning om det där konstiga edge case i din autentiseringsflöde. Några månader senare öppnar du filen och möts av en diger roman fylld med motstridiga instruktioner, föråldrade påminnelser och desperata tillägg som ingen riktigt förstår längre.

Det här är inte bara din upplevelse. Det är ett universellt fenomen.

Forskare som analyserat 247 694 instruktioners livscykel över 1 867 repositories hittade ett slående mönster: agentiska prompts växer inte bara – de växer utan gräns, mer än tredubblas under sin livstid (+226%). I genomsnitt tillför dessa filer +4,9 nettoinstruktioner för varje enskild commit. Filen krymper aldrig. Den expanderar bara.

Men det verkligt fascinerande? Ju äldre en instruktion blir, desto mindre sannolikt är det att den tas bort. Data visar en log-hazard på -0,032 per commit, vilket betyder att instruktioner blir alltmer odödliga ju längre de sitter där. Det är inte så att ingen vill städa – det är att ingen vet om de kan ta bort något säkert.

Problemet med exponentiell osäkerhet

Varför händer detta? Forskarna kallar det "katastrofal ihågkommelse" – motsatsen till det välkända "katastrofala glömska"-problemet i maskininlärning. Men du behöver ingen doktorsexamen för att förstå mekanismen.

Tänk på kostnadskalkylen: att lägga till en ny instruktion är billigt. Du ser ett problem, du skriver en lösning, du går vidare. Den omedelbara kostnaden är låg och den upplevda nyttan är tydlig.

Men att ta bort en instruktion? Det är en helt annan best. Du måste förstå varje ställe där den instruktionen kan spela roll. Du måste resonera kring interaktioner med alla andra instruktioner. Du måste verifiera att borttagningen inte bryter något subtilt och viktigt. Forskarna beräknade denna kognitiva kostnad som O(2^|D|) i en prompt med |D| instruktioner – exponentiell tillväxt alltså, i takt med att instruktionslistan sväller.

Så utvecklare gör vad rationella människor gör: de slutar försöka. Nya instruktioner läggs till. Gamla får stanna. Filen växer.

Kommentarer: Den underskattade hjälten

Här blir forskningen verkligt spännande. Lösningen handlar varken om bättre prompting-tekniker eller smartare modeller. Det är något utvecklare använt sedan programmeringens gryning: kommentarer.

Forskarna tog en intressant metod – de inverterade IFEval, en standardmätning, för att skapa "verifierbara världar" där de optimala promptsen faktiskt är kända. När de lade till kommentarer som kodade latent resonemang i promptsen, minskade den excessiva instruktionstillväxten från +211,3% till bara +1,4%.

Det är en minskning på 99,3%.

Men den riktiga poängen? Dessa kommentarer kontrollerade inte bara tillväxten – de förbättrade faktiskt instruktionsföljandet med upp till 23,1% på verkliga uppgifter. Kommentarer är inte organisatoriskt brus. De är lastbärande strukturer som hjälper AI-assistenter att resonera korrekt om kontext.

Varför detta spelar roll nu

Vi lever genom en fundamental förskjutning i vad "kod" egentligen betyder. Forskarna ställer en tankeväckande fråga: "Om engelska är den nya koden, varför har vi inga kommentarer ännu?"

Det är en rimlig poäng. I decennier har utvecklare förstått att kod utan kommentarer är teknisk skuld. Kommentarer förklarar "varför," inte bara "vad." De fångar intention, edge cases och institutionell kunskap som inte går att utläsa från syntaxen.

Ändå, i vår ivrighet att överlämna mer och mer till AI-kodningsassistenter, har vi behandlat naturliga språkinstruktioner som om de vore något annat. Vi skriver imperativ – gör detta, gör inte detta, kom ihåg att kolla X – utan att förklara vårt resonemang.

Resultatet är det vi ser i de växande CLAUDE.md-filerna: instruktioner som ingen riktigt förstår, som kanske strider mot varandra, och som växer utan någon mekanism för rationalisering.

Vägen framåt

Om du underhåller en CLAUDE.md eller liknande agentisk prompt-fil, här är vad forskningen föreslår:

1. Kommentera dina instruktioner, inte bara din kod. Förklara varför en regel finns. Dokumentera edge cases. Fånga resonemanget bakom beslut.

2. Omfamna periodisk rationalisering. Sluta bara lägga till – skriv om. Forskningen pekar explicit på att fullständiga omskrivningar är ett av få sätt att stoppa tillväxten.

3. Behandla dina AI-instruktioner som onboarding-dokumentation. Skulle du ge en ny utvecklare en 400-raders fil med odifferentierade regler? Din AI-assistent förtjänar samma tydlighet.

Trendkurvan vi är på är inte hållbar. Varje nytt projekt börjar med goda intentioner och slutar med ett ounderhållbart kaos. Men lösningen kanske är enklare än vi trott: skriv för människan (eller AI:n) som läser dina instruktioner om sex månader, inte bara den som svarar på din fråga idag.

Kommentarer är inte brus. De är arkitekturen bakom förståelse.