Kun dokumentaatio muuttuu keräilyprojektiksi

Tunnistan tämän näyn: aloitat uuden projektin tyhjällä CLAUDE.md-tiedostolla. Mukava tippa ohjeita tänne, pari muistutusta sinne. Ehkä varoitus tuosta omituisesta autentikointibugista.

Kuukausia myöhemmin avaat tiedoston ja edessäsi on romaani.

Ristiriitaisia ohjeita. Vanhentuneita muistutuksia. Epätoivoisia liitteitä, joiden merkitystä kukaan ei enää ymmärrä.

Tämä ei ole vain sinun kokemuksesi. Se on universaali ilmiö.

Numerot kertovat karun tarinan

Tutkijat analysoivat 247 694 ohjeen elinkaarta 1 867 repositoriossa. Tulokset ovat hälyttäviä:

Agenttiprompteista ei kasva vain vähän — ne kasvavat hallitsemattomasti. Yli 226 prosenttia alkuperäisestä koosta. Jokainen commit lisää keskimäärin 4,9 ohjetta. Tiedosto ei koskaan kutistu. Se vain paisuu.

Mutta varsinainen juju on tämä: mitä vanhempi ohje on, sitä epätodennäköisemmin sitä poistetaan. Data näyttää log-hazard -arvoa -0,032 per commit. Käytännössä ohjeet muuttuvat ajan myötä yhä kuolemattomammiksi.

Kyse ei ole siitä, etteikö kukaan haluaisi siivota. Ongelma on, ettei kukaan tiedä, voiko jotain turvallisesti poistaa.

Miksi näin käy?

Tutkijat kutsuvat ilmiötä "katastrofaaliseksi muistamiseksi" — se on käänteinen ongelma koneoppimisen "katastrofaaliselle unohtamiselle". Mutta ilman tohtorin hattuakin ymmärtää, mistä tässä on kyse.

Uuden ohjeen lisääminen on halpaa. Näet ongelman, kirjoitat korjauksen, jatkat eteenpäin. Välitön kustannus on pieni, ja hyöty on selvä.

Mutta ohjeen poistaminen? Se on eri eläin. Sinun täytyy ymmärtää jokainen paikka, jossa tuo ohje saattaa olla merkityksellinen. Sinun täytyy päätellä kaikki vuorovaikutukset muiden ohjeiden kanssa. Sinun täytyy varmistaa, että poisto ei riko jotain olennaista.

Tutkijat laskivat tämän kognitiivisen kustannuksen O(2^|D|):ksi — eli se kasvaa eksponentiaalisesti suhteessa olemassa olevien ohjeiden määrään.

Joten kehittäjät tekevät sen, minkä järkevät ihmiset tekevät: he lopettavat yrityksen. Uudet ohjeet lisätään. Vanhat jäävät. Tiedosto kasvaa.

Kommentit: aliarvostettu sankari

Tässä kohtaa tutkimus menee todella mielenkiintoiseksi. Ratkaisu ei ole paremmat promptaustekniikat tai älykkäämmät mallit. Se on jotain, mitä kehittäjät ovat käyttäneet ohjelmoinnin alkuajoista lähtien: kommentit.

Tutkijat käänsivät IfEval-arvostelukehikon päälaelleen. He loivat "todennettavat maailmat", joissa optimaaliset promptit todella tiedetään. Kun he lisäsivät kommentteja, jotka koodasivat piilopäättelyä prompteihin, ylimääräinen ohjekasvu putosi +211,3 prosentista vain +1,4 prosenttiin.

99,3 prosentin vähennys.

Mutta todellinen jytky? Nämä kommentit eivät vain kontrolloineet kasvua — ne paransivat oikeaa ohjeiden noudattamista jopa 23,1 prosenttia todellisissa tehtävissä. Kommentit eivät ole organisatorista sotkua. Ne ovat kantavia rakenteita, jotka auttavat tekoälyassistentteja päättelemään kontekstin oikein.

Miksi tämä on tärkeää juuri nyt

Elämme perustavanlaatuista muutosta siinä, mitä "koodi" tarkoittaa. Tutkijat esittävät provosoivan kysymyksen: "Jos englanti on uusi koodi, miksi siinä ei vielä ole kommentteja?"

Hyvä pointti. Vuosikymmenien ajan kehittäjät ovat ymmärtäneet, että koodi ilman kommentteja on teknistä velkaa. Kommentit selittävät "miksi", eivät vain "mitä". Ne tallentavat tarkoituksen, reunatapaukset ja hiljaisen tiedon, jota ei voi päätellä syntaksista.

Mutta kiirehtimässämme siirtämään yhä enemmän tekoälyavusteisille koodausassistenteille, olemme kohdelleet luonnollisen kielen ohjeita eri lailla. Kirjoitamme käskyjä — tee näin, älä tee noin, muista tarkistaa X — selittämättä päättelyämme.

Tuloksena on se, mitä näemme niissä paisuvissa CLAUDE.md-tiedostoissa: ohjeita, joita kukaan ei täysin ymmärrä, jotka saattavat olla ristiriidassa keskenään, ja jotka kasvavat ilman mitään rationalisointimekanismia.

Mitä sinun kannattaa tehdä?

Jos ylläpidät CLAUDE.md- tai vastaavaa agenttipromptitiedostoa, tutkimus antaa selkeän viestin:

1. Kommentoi ohjeitasi, älä vain koodiasi. Selitä miksi sääntö on olemassa. Dokumentoi reunatapaukset. Tallenna päätösten taustalla oleva päättely.

2. Rakasta säännöllistä rationalisointia. Älä vain lisää — kirjoita uudelleen. Tutkimus toteaa eksplisiittisesti, että kokonaisvaltaiset uudelleenkirjoitukset ovat yksi harvoista asioista, jotka pysäyttävät kasvun.

3. Kohtele tekoälyohjeitasi kuten perehdytysdokumentaatiota. Antaisitko uudelle kehittäjälle 400 riviä erottelemattomia sääntöjä? Tekoälyassistenttisi ansaitsee saman selkeyden.

Kurssi, jolle olemme asettuneet, ei ole kestävä. Jokainen projekti alkaa hyvillä aikomuksilla ja päättyy ylläpitokelvottomaan sekamelskaan.

Mutta korjaus saattaa olla yksinkertaisempi kuin luulimme: kirjoita sitä ihmistä (tai tekoälyä) varten, joka lukee ohjeitasi kuuden kuukauden päästä, älä vain sitä, joka vastaa kysymykseesi tänään.

Kommentit eivät ole sotkua. Ne ovat ymmärryksen arkkitehtuuria.