Speksilähtöinen kehitys ja hyväksymiskriteerit

Promptaus kertoo AI:lle miten tehdä — speksi kertoo mitä tehdä ja milloin se on valmis. Tässä oppitunnissa opit kirjoittamaan speksejä, jotka ohjaavat AI:ta tuottamaan juuri oikean lopputuloksen.

Miksi speksi ennen koodia?

Speksilähtöinen kehitys

Speksilähtöinen kehitys (spec-driven development) tarkoittaa, että jokainen ominaisuus kuvataan täsmällisenä speksinä ennen toteutusta. Speksi sisältää tavoitteen, hyväksymiskriteerit, tiedostot, jotka muuttuvat, ja testausstrategian. AI-agentti käyttää speksiä suunnitelmana ja tarkistuslistana.

Speksi vs. prompti

Aspekti	Prompti	Speksi
Tarkoitus	Yksittäinen pyyntö	Kokonainen ominaisuus
Laajuus	1–5 lausetta	Strukturoitu dokumentti
Verifioitavuus	Subjektiivinen	Objektiivinen (AC:t)
Toistettavuus	Heikko	Vahva
Arvo pitkällä aikavälillä	Katoava	Dokumentaatio

Speksin rakenne

Speksipohjamarkdown

# Feature: Käyttäjän profiilisivu

## Tavoite
Käyttäjä näkee oman profiilinsa tiedot ja voi muokata niitä.

## Hyväksymiskriteerit

### AC1: Profiilin näyttäminen
**Given** kirjautunut käyttäjä
**When** navigoi osoitteeseen /profile
**Then** näkee nimensä, sähköpostinsa ja profiilikuvansa

### AC2: Nimen muokkaus
**Given** kirjautunut käyttäjä profiilisivulla
**When** muokkaa nimeä ja painaa Tallenna
**Then** nimi päivittyy tietokantaan ja UI:ssa

### AC3: Virheenkäsittely
**Given** kirjautunut käyttäjä profiilisivulla
**When** yrittää tallentaa tyhjän nimen
**Then** näkee virheilmoituksen "Nimi ei voi olla tyhjä"

## Tiedostot
| Tiedosto | Muutos |
|----------|--------|
| app/profile/page.tsx | Uusi sivu |
| lib/users/profile.ts | Profiilifunktiot |
| components/ProfileForm.tsx | Lomakekomponentti |

## Testausstrategia
- Yksikkötestit: ProfileForm validointi
- Integraatiotesti: profiilin tallennus
- E2E: koko profiilimuokkausflow

Hyväksymiskriteerit: Given-When-Then

Given-When-Then on tehokkain tapa kirjoittaa hyväksymiskriteereitä, koska jokainen kriteeri on suoraan käännettävissä testiksi.

Given — Esiehto

Mikä tilanne vallitsee ennen toimintoa? Kirjautunut käyttäjä? Tyhjä tietokanta? Tietty sivu auki?

When — Toiminto

Mitä tapahtuu? Käyttäjä klikkaa nappia? API vastaanottaa pyynnön? Ajastettu tehtävä käynnistyy?

Then — Odotettu tulos

Mikä on lopputulos? UI näyttää tietoa? Tietokanta päivittyy? Sähköposti lähtee?

Pro-vinkki

Jokainen hyväksymiskriteeri pitäisi voida suoraan kääntää testiksi. Jos kriteeriä ei voi testata automaattisesti, se on todennäköisesti liian epämääräinen. Kirjoita kriteeri uudelleen täsmällisemmin.

Testaa kriteerisi kolmella kysymyksellä

“Testattavissa” on helppo sanoa ja vaikea tarkistaa. Kolme kysymystä, jotka tekevät siitä konkreettista — käytä näitä jokaiseen kirjoittamaasi AC:hen:

Onko siinä täsmällinen odotettu arvo tai tuloste? Ei “sopiva viesti” vaan se merkkijono, joka näytölle tulee.
Voisiko toinen ihminen kirjoittaa tästä testin kysymättä sinulta mitään? Jos hän joutuisi kysymään “mitä tarkoitat”, kriteeri ei ole valmis.
Voiko se mennä rikki? Jos AC ei voi epäonnistua millään toteutuksella, se ei todista mitään.

Sovelletaan tätä yllä olevaan esimerkkiin

Esimerkkispeksin AC3 läpäisee kaikki kolme: se nimeää tarkan merkkijonon, kuka tahansa osaa kirjoittaa siitä testin, ja se menee rikki jos validointi puuttuu.

AC1 ja AC2 eivät läpäise — ja se on tyypillistä, koska ne kuulostavat riittävän täsmällisiltä:

Alkuperäinen	Miksi ei riitä	Uudelleen kirjoitettuna
“…näkee nimensä, sähköpostinsa ja profiilikuvansa”	Mitä “näkee” tarkoittaa testinä? Mitä jos kuva on rikkinäinen linkki?	“…sivulla on käyttäjän `name` ja `email` tekstinä, ja `img[alt="profiilikuva"]`-elementin `src` osoittaa käyttäjän `avatar_url`-arvoon”
“…nimi päivittyy tietokantaan ja UI:ssa”	Kaksi väitettä yhdessä, kumpikaan ilman tarkistettavaa arvoa	“…`users.name` on tietokannassa uusi arvo, ja sivun uudelleenlatauksen jälkeen otsikko näyttää saman arvon”

Pro-vinkki

Huomaa, mitä uudelleenkirjoitus tekee: se ei lisää vaatimuksia vaan päättää asioita, jotka olivat auki. Juuri siksi tämä on kehittäjän työtä eikä muotoseikka — jokainen epämääräinen AC on päätös, jonka joku muu (usein malli) tekee puolestasi myöhemmin. Viikon vertaispalaute kysyy sinulta täsmälleen tätä: nimeä yksi AC, joka ei ole testattava, ja kirjoita se uudelleen.

Speksi ohjaa AI:ta

Kun annat AI-agentille speksin promptin sijaan, agentti:

Ymmärtää laajuuden — tietää, mitä tiedostoja luoda/muokata
Tarkistaa työnsä — vertaa tulosta hyväksymiskriteereihin
Priorisoi — aloittaa kriittisimmistä kriteereistä
Dokumentoi — speksi toimii muutoksen dokumentaationa

Speksi AI-agentillemarkdown

Toteuta seuraava speksi:

# Feature: Hakutoiminto

## AC1: Perushaku
Given käyttäjä on hakusivulla
When kirjoittaa hakukenttään "React" ja painaa Enter
Then näkee listan tuloksista, jotka sisältävät "React"

## AC2: Tyhjä haku
Given käyttäjä on hakusivulla
When painaa Enter tyhjällä hakukentällä
Then näkee ilmoituksen "Kirjoita hakutermi"

## AC3: Ei tuloksia
Given käyttäjä on hakusivulla
When hakee termillä "xyznonexistent123"
Then näkee ilmoituksen "Ei hakutuloksia"

Tiedostot:
- app/search/page.tsx (uusi)
- components/SearchBar.tsx (uusi)
- lib/search/searchService.ts (uusi)

Noudata projektin AGENTS.md-sääntöjä.
Kirjoita testit ennen toteutusta (TDD).

Speksien laadun tarkistuslista

Ennen kuin annat speksin AI:lle, tarkista:

Jokainen AC on testattavissa
Given-When-Then on täydellinen (ei puuttuvia osia)
Tiedostolista on realistinen
Virhetilanteet on huomioitu
Edge caset on tunnistettu
Speksi on linjassa AGENTS.md:n kanssa

Tietovisa

Mikä on Given-When-Then -mallin suurin etu AI-avusteisessa kehityksessä?

Iteratiivinen speksityö

Speksi harvoin syntyy kerralla. Käytä iteratiivista prosessia:

Luonnos — Kirjoita ensimmäinen versio nopeasti
Tarkistus — Käy läpi tarkistuslista
AI-arviointi — Pyydä AI:ta arvioimaan speksin selkeyttä
Jalostus — Lisää puuttuvat edge caset ja virhetilanteet
Hyväksyntä — Speksi on valmis toteutettavaksi

Kirjoita speksi oikealle ominaisuudelle

Valitse oikea tai kuvitteellinen ominaisuus ja kirjoita sille täydellinen speksi: 1) Tavoite, 2) Vähintään 3 hyväksymiskriteeriä Given-When-Then -muodossa, 3) Tiedostolista, 4) Testausstrategia. Anna speksi AI-koodaustyökalulle ja arvioi tulosta.

Yhteenveto

Speksi kertoo AI:lle mitä tehdä ja milloin se on valmis
Given-When-Then on standardi hyväksymiskriteerien kirjoittamiseen
Jokainen kriteeri pitää olla testattavissa
Speksi sisältää tavoitteen, AC:t, tiedostolistan ja testausstrategian
Seuraavaksi yhdistämme kaiken: TDD tekoälyn kanssa — ensimmäinen projekti