Corpus omaan repoon: mitä hakemistoon kannattaa laittaa ja mitä ei – Corpus 3/3
AI
Moni olettaa, että Corpuksen käyttöönotto on iso dokumentointiprojekti. Ensimmäinen versio syntyy suunnilleen yhden kahvitauon aikana.
Teksti: Arttu Ylärakkola
Lyhyt ohje kiireisille
Juttele kanssamme (arttu@rakettitiede.com), niin saat Corpus-pdf:n.
Tiputa pdf projektisi versionhallintaan.
Sano tekoälylle: "Lue tämä pdf ja otetaan Corpus käyttöön."
Mene kahville.
Kun tulet takaisin, ensimmäinen versio Corpuksesta odottaa koneellasi.
Pdf kertoo tekoälylle, mikä Corpus on ja miten sen kanssa toimitaan. Loput se päättelee repostasi. Se lukee koodin, dokumentit ja historian, luonnostelee hakemiston ja kytkee päivittämisen työnkulkuun. Mitään ei tarvitse ostaa, asentaa tai opetella.
Eikä kohta 1 ole mikään myyntipuhelu: haluamme kuulla, miten teillä tekoälyä käytetään, ja molemmat oppivat jotain.
Valitse yksi repo
Corpus on hakemisto markdown-tiedostoja projektin versionhallinnassa. Tiedostot kuvaavat järjestelmän liiketoiminnan tasolla, ja ne on kirjoitettu niin, että niitä voi lukea kehittäjä, liiketoiminnan ihminen tai tekoäly.
Aloita yhdestä pilotista. Hyvä ehdokas on aktiivisessa kehityksessä oleva projekti, jossa on paljon käyttäjäpolkuja ja prosesseja: tilauksia, hyväksyntöjä, rooleja ja poikkeustapauksia.
Huono ehdokas on tiukasti speksattu, puhtaasti tekninen API-mikropalvelu. Siitä koodi ja rajapintakuvaus kertovat jo lähes kaiken, eikä Corpus tuo paljon lisää.
Älä aloita tyhjältä sivulta
Ensimmäistä versiota ei kirjoiteta käsin. Se generoidaan siitä, mitä teillä jo on: Confluence-sivuista, Word- ja PDF-spekseistä, kalvosarjoista, arkkitehtuurikuvauksista, Jira-tiketeistä, ADR:istä, README-tiedostoista, commit-historiasta ja itse koodista. Tämän osan tekoäly hoitaa kahvipaussisi aikana. Corpus-pdf kertoo tekoälylle, mitä tavoitellaan.
Kahvittelun jälkeen tulee vaihe, jolla on oikeasti väliä. Käy luonnos läpi liiketoiminnan tuntevien ihmisten kanssa. Heidän ei tarvitse kirjoittaa mitään. Riittää, että he sanovat "tämä on väärin" ja "tuo on vanhentunut". Kyse on tarkistustyöstä eikä dokumentointiprojektista. Siihen tarvitaan toimialan tuntemusta, ei teknistä osaamista.
Mitä hakemistoon kannattaa laittaa?
Sanasto. Mitä termit tarkoittavat juuri tässä järjestelmässä ja tässä yrityksessä? Softaprojekteissa samalla asialla on usein monta nimeä: yksi tietokannassa, toinen koodissa, kolmas käyttöliittymässä, neljäs käyttäjien puheissa ja viides mainosmatskuissa. Yhteinen sanasto on yllättävän iso osa hyödystä, koska se vähentää väärinymmärryksiä niin ihmisten kuin tekoälyn kanssa.
Roolit. Jokaisesta käyttäjäroolista kirjataan kolme asiaa:
mikä rooli on ja mitä se konkreettisesti tekee,
mitä se haluaa tehdä ja mitä ei,
mitä sen pitää nähdä ja pystyä tekemään ja mitä ei.
Kolmas kohta kuvataan käsitteiden tasolla eikä kenttä kentältä. Tarkempi kuvaus on jo koodissa, eikä sitä kannata kopioida Corpukseen. Toinen kohta eli roolin motiivit unohtuu helpoimmin, ja juuri sitä tekoäly ei pysty päättelemään koodista.
Prosessit. Mitä tapahtuu ja missä järjestyksessä? Mermaid-kaaviot sopivat tähän hyvin. Niiden lähdekoodi on tekoälylle helppolukuista tekstiä, ja ihminen saa samasta tiedostosta kuvan.
Mitä hakemistoon ei kannata laittaa?
Suunnitelmia järjestelmän tulevasta tilasta. Tekoäly menee helposti sekaisin siitä, kuvaako Corpus nykyistä vai suunniteltua tilaa. Corpus kuvaa sitä, mikä on totta nyt. Suunnitelmat kuuluvat muualle.
Käyttöliittymän kuvauksia. Tekoäly päättelee käyttöliittymän lähdekoodista erittäin hyvin. Sen kirjoittaminen tekstiksi on turhaa työtä, joka vain vanhenee.
Mitään, mikä vanhenee helposti. Kuvakaappaukset ovat pahimpia, koska tekoälyltä kestää niiden tulkitsemisessa, ja niiden päivittäminen vie ihmisiltä aikaa.
Kytke Corpus työnkulkuun
Corpus, jota kukaan ei muista päivittää, on vain yksi vanhentunut dokumentti lisää. Siksi päivitys kytketään arkeen. AGENTS.md, commit hook tai mikä tahansa teille sopiva keino kertoo tekoälylle, että Corpus luetaan ennen työtä ja päivitetään työn yhteydessä. Pidä tämä yksinkertaisena.
Definition of doneen tulee yksi rivi: jokainen pull request, joka muuttaa järjestelmän toimintaa, päivittää myös Corpuksen, ja Corpuksen diff katselmoidaan.
Hyvä uutinen on, että tekoäly kirjoittaa Corpusta ja pitää sen ajan tasalla yllättävän hyvin. Huono uutinen on, että se ei omatoimisesti pilko liian pitkäksi kasvanutta tiedostoa pienemmiksi, vaikka pienistä tiedostoista se saisi kontekstin tehokkaammin käyttöön. Siitä pitää muistuttaa aina välillä.
Kuka tätä kaikkea lukee?
On hyvä pitää mielessä, ettei kenenkään tarvitse lukea sitä kannesta kanteen kuten käsikirjaa. Arjessa ihmiset lukevat joko diffin, kun jotain muutetaan, tai tekoälyn vastauksen, joka perustuu Corpukseen. Kysymys esitetään tekoälylle, eikä kenenkään tarvitse metsästää tietoa tiedostoista, jotka saattavat olla vanhentuneita.
Vastaus myös mukautuu kysyjään. Kehittäjä saa arkkitehtuuria ja kompromisseja, ei-tekninen tuoteomistaja käsitetason vastauksen. Tätä voi hienosäätää määrittelemällä eri roolit komennoiksi tai skilleiksi.
Mistä tiedät, että tämä toimii?
Arvioi tilannetta parin viikon päästä. Suurimmat hyödyt eivät välttämättä näy ensimmäisessä commitissa.
Ne näkyvät, kun vastaan tulee huonosti kirjoitettu tiketti jostain monimutkaisesta toiminnosta, jota kehittäjät eivät ymmärrä, mutta tekoäly pystyy selittämään sen Corpuksen avulla. Tai kun uusi kehittäjä kysyy Corpukselta sen sijaan, että arvailisi, mitkä dokumentit ovat ajan tasalla.
Työ ei mene hukkaan, vaikka työkalut vaihtuisivat. Vuoden 2030 kehitystyökalut voivat olla aivan muuta kuin nykyiset, mutta nekin tarvitsevat jonkun kertomaan, mitä järjestelmän pitää tehdä: säännöt, roolit, prosessit ja päätökset. Kukaan ei tiedä, missä muodossa se silloin kerrotaan. Tieto on kuitenkin samaa, jota kirjaat Corpukseen nyt.
Ja vaikka työkalut vaihtuisivat, työ ei mene hukkaan. Vuoden 2030 kehitystyökalut voivat olla aivan muuta kuin nykyiset, mutta nekin tarvitsevat jonkun kertomaan, mitä järjestelmän pitää tehdä: säännöt, roolit, prosessit ja päätökset. Kukaan ei tiedä, missä muodossa se silloin kerrotaan. Tieto on kuitenkin samaa, jota kirjaatte Corpukseen nyt – ja myös vuoden 2030 työkalut osaavat lukea Corpusta.
Lue Corpus-sarjan kaikki osat:
1/3: Teknisesti täydellinen, käytännössä väärä: miksi nopea koodi synnyttää kognitiivista velkaa
2/3: Koodi väärin, Corpus väärin vai molemmat? Kolme ristiriitaa, jotka paljastavat enemmän kuin testit
3/3: Corpus omaan repoon: mitä hakemistoon kannattaa laittaa ja mitä ei (eiku senhän sä just luit!)
Mikä on Corpus?
Corpus on projektin versionhallinnassa oleva hakemisto markdown-tiedostoja. Ne kuvaavat järjestelmän liiketoiminnan tasolla: sanaston, käyttäjäroolit ja niiden motiivit, prosessien kulun sekä tehdyt päätökset. Tiedostoja voi lukea kehittäjä, liiketoiminnan ihminen tai tekoäly, ja ne päivitetään aina, kun järjestelmän toiminta muuttuu.
Koodi kertoo tekoälylle, miten järjestelmä toimii. Corpus kertoo, miksi.
Corpus ei ole tuote eikä siihen ole lisenssiä. Se on pelkkä versioitu hakemisto tekstitiedostoja, joten se toimii minkä tahansa kielen, työkalun ja menetelmän kanssa. Emme väitä keksineemme sitä. Ajauduimme tähän työtapaan omissa projekteissamme ja annoimme sille nimen Corpus.
Esimerkkirepo: github.com/rakettitiede/corpus