Spec-ohjattu kehitys AI-agenttien kanssa: 9 milestonea, 17 taskia ja yksi pyhä sääntö

Huomio nimistä: Tämä kirjoitus perustuu omaan, oikeaan työhöni. Yritysten ja toimittajien nimet on keksitty, eikä luottamuksellista dataa jaeta. Menetelmät ja opit ovat aitoja ja sellaisenaan käyttökelpoisia.

AI-agentit kirjoittavat koodia nopeammin kuin ehdin lukea sitä. Se on ongelma: ilman rakennetta nopeus muuttuu entropiaksi. Paras tähän mennessä löytämäni vastaus on spec-ohjattu kehitys, jolla rakensin verkkokaupan tuotedatan hallintajärjestelmän – työkalun, joka pitää tuhansien tuotteiden tiedot, hinnat ja kustannukset ajan tasalla toimittajien aineistojen pohjalta.

Projekti eteni yhdeksän milestonen ja seitsemäntoista taskin läpi muutamassa päivässä. Tässä malli, joka teki sen mahdolliseksi.

Sykli: spec → toteutus → katselmointi → arkistointi

Jokainen työvaihe kulkee saman putken läpi:

1. Spec. Ennen riviäkään koodia task määritellään: tavoite, rajaukset, hyväksymiskriteerit. Speksin kirjoittaa AI, mutta minä hyväksyn sen.
2. Toteutus. Agentti toteuttaa taskin speksiä vasten – ei enempää, ei vähempää.
3. Spec-review. Toteutus katselmoidaan hyväksymiskriteerejä vasten. Hyväksytty task arkistoidaan; hylätty palaa toteutukseen.
4. Milestone-kirjanpito. Roadmap päivittyy jokaisen hyväksynnän jälkeen, joten projektin tila on aina luettavissa yhdestä paikasta.

Kuulostaa byrokraattiselta, mutta on käytännössä kevyt: yhden taskin spec on tyypillisesti alle sivun. Vastineeksi jokainen commit-historian rivi kertoo, mikä hyväksyttiin ja milloin – TASK-004: two-pass validation framework ja perässä spec-review TASK-004: accept, archive.

Yksi pyhä sääntö: käsin tehty muutos on koskematon

Järjestelmä kirjoittaa tuotedataa, jota myös ihmiset muokkaavat käsin. Tästä syntyi projektin tärkein yksittäinen sääntö, jota kutsun nimellä hand-edit-sacred: automaatio ei koskaan ylikirjoita kentän arvoa, jonka ihminen on muuttanut, ellei sitä eksplisiittisesti käsketä.

Merge-moottori toteuttaa tämän vertaamalla kolmea tilaa: mitä automaatio kirjoitti viimeksi, mikä kentän arvo on nyt, ja mitä uusi aineisto ehdottaa. Jos nykyarvo poikkeaa automaation viimeksi kirjoittamasta, joku on koskenut siihen käsin – ja kenttä jätetään rauhaan. Ilman tätä sääntöä yksikään kauppias ei uskalla päästää automaatiota tuotedatansa lähelle.

Muut kantavat rakenteet

SKU-first-täsmäytys. Toimittajan aineiston rivit yhdistetään kaupan tuotteisiin ensisijaisesti SKU:lla, ja vasta toissijaisesti heuristiikoilla. Epävarma täsmäytys on pahempi kuin puuttuva: väärään tuotteeseen kirjoitettu hinta on myrkkyä.

Diff-moottori ja suunnitelma ennen kirjoitusta. Mikään ei kirjoita suoraan kauppaan. Täsmäytys + merge + validointi tuottavat ensin DiffPlanin – luettavan listan siitä, mitä muuttuisi. Vasta hyväksytty suunnitelma ajetaan, ja ajosta jää snapshot ja audit-loki, joten jokainen muutos on jäljitettävissä ja peruttavissa.

Kaksivaiheinen validointi. Ensin aineisto validoidaan itsenäisesti (rakenne, tyypit, pakolliset kentät), sitten kaupan nykytilaa vasten (onko tuote olemassa, onko muutos järkevä). Erottelu tekee virheilmoituksista täsmällisiä.

Tokenitehokkuussopimus. Kun agentit operoivat isolla tuotemassalla, kontekstin koko on oikea kustannus. Määrittelin operaatioille kontraktin, jossa massaoperaatiot (esim. joukkouudelleennimeäminen mapping-tiedostosta) kulkevat tiiviissä muodossa – ei tuhansia rivejä JSON:ia agentin kontekstiin.

SOP CLAUDE.md:ssä. Projektin vakiotoimintatavat – miten taskit ajetaan, mitä katselmoinnissa tarkistetaan, mitkä ovat avoimet kysymykset – elävät repossa agenttien ohjetiedostossa. Uusi sessio jatkaa siitä, mihin edellinen jäi, ilman suullista perimätietoa.

Toimiiko se?

Kahden ensimmäisen päivän aikana putkesta valmistui scaffold, konfiguraatioloaderit, merge-moottori, validointikehys, täsmäytys, diff-moottori, snapshotit ja ajo-orkestrointi – jokainen katselmoituna. Kolmantena päivänä tein tasks 1–9:lle vielä erillisen bulk-verifiointipassin: kävin hyväksytyt taskit läpi uudelleen yhtenä kokonaisuutena. Sieltä löytyi saumakohtia, joita yksittäiset katselmoinnit eivät nähneet.

Se on rehellinen yhteenveto AI-agenteista tuotekehityksessä juuri nyt: vauhti on todellista, mutta laatu tulee rakenteesta – speceistä, katselmoinneista ja säännöistä, jotka sinä asetat ja omistat.