Dokumentaatio on nyt ajettavaa koodia

“Kirjoita dokumentaatiota” on yksi niistä ohjeista, jotka kaikki nyökkäävät kokouksessa ja jotka sitten unohtuvat heti kun deadline lähestyy. Nyt sama neuvo kiertää uudessa muodossa: tiimeille kerrotaan, että repon README ja onboarding-ohjeet pitää kirjoittaa kunnolla, koska muuten tekoälyagentti ei osaa toimia oikein. Väite on tuttu vanhassa kuosissa, vain kohdeyleisö on vaihtunut ihmisestä koneeseen.

Tunnustan heti kärkeen, että vanha neuvo oli oikeassa periaatteen tasolla. Hyvä dokumentaatio on aina ollut hyväksi: se nopeuttaa perehdytystä, vähentää saman kysymyksen kysymistä uudestaan ja tekee projektista siirrettävän, jos joku muu joutuu jatkamaan sitä. Kukaan ei ole koskaan väittänyt, että huono dokumentaatio olisi parempi vaihtoehto. Käytännön ongelma oli sen kirjoittamatta jättäminen: dokumentaatio jäi tekemättä, koska sen lukijakunta oli epämääräinen ja motivaatio kirjoittaa jollekin, joka ehkä joskus lukee tekstin, on aina heikko. Moni tiimi eli tällä logiikalla vuosia, ja usein se jopa toimi, koska tieto siirtyi suullisesti sen ihmisen kautta, joka sattui muistamaan mihin projekti viime kerralla jäi ja miksi jokin ratkaisu tehtiin juuri niin. Kun se ihminen oli lomalla tai vaihtoi tiimiä, tieto katosi hetkeksi, mutta yleensä joku toinen ehti kaivaa sen esiin ennen kuin siitä koitui oikeaa vahinkoa.

Mikä oikeasti muuttui

Kaikissa projekteissani dokumentaation rooli on siirtynyt samaan suuntaan, ja tämä ei ole enää periaate vaan päivittäinen havainto. Repoissani on CLAUDE.md-tiedosto, joka toimii AI:n sääntökirjana: siihen on kirjattu tekniset gotchat, jotka estävät tyypillisimmät virheet ennen kuin ne ehtivät tapahtua. Kun agentti aloittaa session, se lukee tämän tiedoston ensin, ja jos siellä lukee “älä koskaan tapa tätä porttia komennolla X, koska se katkaisee myös kehittäjän oman selainyhteyden”, agentti ei tee sitä virhettä. Kirjoitin tästä mokasta tarkemmin aiemmassa kirjoituksessani: ihminen olisi voinut lukea saman ohjeen kerran vuosi sitten ja unohtaa sen seuraavana viikkona, mutta agentti lukee sen joka ikinen kerta.

Pyöräpassi-projektissa sama periaate näkyy runbookeina: deploy-ohje, backup-restore-ohje ja infra-gotchat on kirjoitettu auki niin tarkasti, että yksi ihminen pystyy pyörittämään tuotantoympäristöä ilman että jokainen operaatio vaatii uutta muistelua siitä, miten tämä nyt tehtiinkään viime kerralla. Runbook ei ole enää ylellisyys, jonka isompi tiimi voisi kirjoittaa joskus. Se on ehto sille, että yksi henkilö ylipäätään voi hoitaa tuotanto-opsia turvallisesti.

Kolmas esimerkki on muistijärjestelmä: hakemisto markdown-tiedostoja, jotka kantavat projektikontekstin session yli. Tämä blogitekstin taustalla oleva ideapankkikin syntyi juuri tästä logiikasta, koska sen olemassaolo mahdollistaa sen, että seuraava kirjoitussessio jatkuu suoraan siitä, mihin edellinen jäi. Aiemmin sama kontekstin palautus tapahtui ihmisen päässä: avasin edellisen session muistiinpanot, luin ne läpi ja yritin palauttaa mieleen missä kohtaa jäin. Nyt agentti lukee saman tiedon rakenteisena tekstinä ja jatkaa siitä suoraan, ilman että kukaan selittää tilannetta uudestaan ääneen.

Kun aukko ei jää huomaamatta vaan ajetaan

Klassinen dokumentaation ongelma oli, ettei kukaan lue sitä, jolloin puutteellinen ohje aiheutti korkeintaan hämmennystä: käyttäjä klikkasi vähän aikaa väärää nappia ja löysi lopulta oikean polun, tai kysyi kollegalta. Käänteinen puoli tulee nyt vastaan konkreettisesti. Erään sisäisen dokumentaatiosivuston onboarding-ohjeessa oli aukko siinä, mistä organisaatiosta uuden tuotesivuston repo piti hakea. Ihminen olisi lukenut ohjeen, huomannut epäselvyyden ja kysynyt varmistuksen kollegalta ennen kuin olisi tehnyt mitään. AI-agentti sen sijaan täytti aukon parhaalla arvauksellaan ja haki väärän organisaation repot, koska sillä ei ollut mekanismia pysäyttää itseään ja sanoa “tämä kohta on epäselvä”. Se ei jäänyt harkitsemaan, se toimi heti sen tulkinnan mukaan, joka sattui olemaan käsillä. Dokumentoimaton askel ei jäänyt lukematta. Se muuttui suoraan vääräksi toiminnaksi, ja jälkikäteen korjaus vei enemmän aikaa kuin puuttuvan rivin kirjoittaminen ohjeeseen olisi alun perin vienyt.

Tästä seuraa oma kantani: “kirjoita dokumentaatiota” oli ennen hygieniasaarna, samaa sarjaa kuin “tee varmuuskopiot” tai “kirjoita testejä”, eli asia jonka kaikki tiesivät mutta jonka laiminlyönnin kustannus oli hajautunut ja epämääräinen. Nyt se on suora tuottavuusinvestointi, koska lukijana on kone joka lukee tekstin kirjaimellisesti joka ikinen session ja koska ihminen ei koskaan lue sitä uudestaan sen jälkeen kun on sen itse kirjoittanut. Vaikutus näkyy arjessa kahdella tavalla: agentti ei toista kertaalleen dokumentoitua virhettä, ja “missä minä jäinkään” -kontekstin palautus session alussa kestää sekunteja eikä minuutteja.

Perustan tämän kannan siihen, että olen itse kirjoittanut nämä kolme tyyppiä (sääntökirja, runbook, muistitiedosto) ja seurannut mitä eroa niillä on ollut ennen ja jälkeen. Ero on hyvin konkreettinen: sama virhe ei toistu, koska se on kirjoitettu ylös sinne, mistä agentti sen aina löytää.

Mitä siis kannattaa kirjoittaa

Tästä ei silti seuraa, että kaikki pitäisi dokumentoida yhtä perusteellisesti. Käytännön ohjeeni on rajaava: dokumentoi se, mikä on yllättävää tai kiellettyä, älä sitä minkä koodi jo kertoo. Koodi kertoo itse, mitä funktio tekee, jos sitä lukee. Koodi ei kerro, miksi tietty komento on kielletty tuotannossa, miksi jokin näennäisesti järkevä ratkaisu ei toimi tässä ympäristössä, tai mistä organisaatiosta repot pitää oikeasti hakea. Gotchat ja rajaukset ovat juuri se tieto, joka katoaa ihmisen päästä ja jota agentti ei voi päätellä koodista, koska se on kokemusperäistä tietoa aiemmista virheistä.

Päättäjän kannalta tämä tarkoittaa yhtä konkreettista päätöstä: jos tiimissä käytetään AI-agentteja koodaukseen, opsiin tai sisällöntuotantoon, dokumentaation kirjoittamiselle pitää varata aikaa samalla tavalla kuin testien kirjoittamiselle, eikä sitä pidä jättää “kun ehditään” -listalle. Tämä on nyt osa sitä infraa, jonka varassa agentti toimii oikein, ja siihen kannattaa suhtautua yhtä vakavasti kuin palvelimen varmuuskopiointiin. Jos budjetti tähän puuttuu, se kannattaa tunnistaa riskinä. Käytännössä riittää usein pieni tapa: kun agentti tekee virheen tai kysyy jotain, mitä olisi voinut päätellä ohjeesta, se rivi kirjataan heti sinne mistä agentti sen ensi kerralla löytää, eikä jätetä muistin varaan.

Mikä muuttaisi mieleni

Tämä on tämän hetken näkemykseni, ja se perustuu siihen kokemukseen, joka minulla on tähän mennessä kertynyt CLAUDE.md-tiedostoista, Pyöräpassin runbookeista ja muistijärjestelmästä. Jos agentit alkavat luotettavasti kysyä varmistusta epäselvissä kohdissa sen sijaan että täyttävät aukon arvauksella, tämän tekstin ydinperuste heikkenee, koska silloin dokumentaation aukko palaisi takaisin hämmennykseksi eikä vääräksi teoksi. Siihen asti pidän kiinni siitä, että dokumentaatio on ajettavaa koodia siinä missä se ennen oli vain luettavaa tekstiä.