Når dokumentasjon blir et arkivskap ingen tørr røre

Tenk deg dette: du starter et nytt prosjekt med en nydelig tom CLAUDE.md-fil. Noen smarte tips. Et par kontekstnotater. En advarsel om den rare edge casen i autentiseringsflyten din. Måneder senere åpner du fila, og den har blitt en diger roman av motstridende instrukser, utdaterte påminnelser og desperate vedlegg som ingen lenger helt forstår.

Dette er ikke bare din opplevelse. Det er et universelt fenomen.

Tallene som sjokkerer

Forskning som analyserte 247 694 instruksjoners levetid på tvers av 1 867 repositorier avslørte et urovekkende mønster: agentiske prompts vokser ikke bare – de vokser uten grenser. Over operativ levetid øker de med over 226 prosent. I gjennomsnitt legger disse filene til 4,9 flere instrukser for hver eneste commit. Filen krymper aldri. Den bare vokser.

Men her kommer det virkelig fascinerende: jo eldre en instruks blir, jo mindre sannsynlig er det at den blir slettet. Dataene viser en log-hazard på -0,032 per commit. Instrukser blir altså stadig mer udødelige jo lenger de sitter der. Det er ikke sånn at ingen ønsker å rydde opp – det er at ingen tør fjerne noe.

Hvorfor skjer dette?

Forskerne kalte det «katastrofal hukommelse» – det motsatte av det velkjente «katastrofal glemsel»-problemet i maskinlæring. Men du trenger ingen doktorgrad for å forstå mekanismen.

Tenk på kostnadsberegningen: å legge til en ny instruks er billig. Du ser et problem, skriver en løsning, går videre. Den umiddelbare kostnaden er lav, og den opplevde nytten er klar.

Men å fjerne en instruks? Det er en helt annen skapning. Du må forstå hvert eneste sted der den instruksen kan ha betydning. Du må resonere om samspillet med alle de andre instruksene. Du må verifisere at fjerningen ikke ødelegger noe subtilt og viktig. Forskerne beregnet denne kognitive kostnaden som O(2^|D|) i en prompt med |D| instrukser – altså eksponentiell vekst.

Så utviklere gjør det som rasjonelle mennesker gjør: de slutter å prøve. Nye instrukser legges til. Gamle blir værende. Filen vokser.

Kommentarer: Helten vi overser

Her blir forskningen virkelig spennende. Løsningen verken er bedre prompting-teknikker eller smartere modeller. Det er noe utviklere har brukt siden programmeringens gryning: kommentarer.

Forskerne tok en interessant tilnærming – de invertierte IFEval, en standard benchmark, for å skape «verifiserbare verdener» der de optimale promptene faktisk er kjent. Da de la til kommentarer som kodet latent resonnement i promptene, falt den eksessive instruksveksten fra +211,3 prosent til bare +1,4 prosent.

Det er en reduksjon på 99,3 prosent.

Men det virkelige poenget? Disse kommentarene kontrollerte ikke bare veksten – de forbedret faktisk instruks-oppfølgingen med opptil 23,1 prosent på virkelige oppgaver. Kommentarer er ikke bare organisatorisk rot. De er bærende strukturer som hjelper AI-assistenter med å resonnere om kontekst på riktig måte.

Hvorfor dette betyr noe nå

Vi lever gjennom et fundamentalt skifte i hva «kode» betyr. Forskerne stiller et provoserende spørsmål: «Hvis engelsk er den nye koden, hvorfor har vi ikke kommentarer ennå?»

Det er et rettferdig poeng. I tiår har utviklere forstått at kode uten kommentarer er teknisk gjeld. Kommentarer forklarer «hvorfor», ikke bare «hva». De fanger intensjon, edge cases og institusjonell kunnskap som ikke kan utledes fra syntaks alene.

Men i hastverket med å overlate mer og mer til AI-kodingsassistenter, har vi behandlet naturlige språkinstrukser som om de var noe annet. Vi skriver imperativer – gjør dette, ikke gjør det, husk å sjekke X – uten å forklare resonnementet vårt.

Resultatet er det vi ser i de svulmende CLAUDE.md-filene: instrukser som ingen helt forstår, som kanskje strider mot hverandre, og som vokser uten noen mekanisme for rasjonalisering.

Veien videre

Hvis du vedlikeholder en CLAUDE.md eller lignende agentisk prompt-fil, her er hva forskningen antyder:

1. Kommenter instruksjonene dine, ikke bare koden din. Forklar hvorfor en regel eksisterer. Dokumenter edge cases. Ta vare på resonnementet bak avgjørelser.

2. Omfavn periodisk rasjonalisering. Ikke bare legg til – omskriv. Forskerne påpeker eksplisitt at helhetlige omskrivninger er en av de eneste tingene som stopper veksten.

3. Behandl AI-instruksjonene dine som onboarding-dokumentasjon. Ville du gitt en ny utvikler en 400-linjers fil med udifferentierte regler? AI-assistenten din fortjener samme klarhet.

Utsiktene vi er på er ikke bærekraftige. Hvert nytt prosjekt starter med gode intensjoner og ender med et uvedlikeholdbart kaos. Men løsningen kanskje er enklere enn vi trodde: skriv for mennesket (eller AI-en) som leser instruksjonene dine om seks måneder, ikke bare den som svarer på spørsmålet ditt i dag.

Kommentarer er ikke rot. De er arkitekturen til forståelse.