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?

Speksi vs. prompti

Speksin rakenne

# 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?

Speksi ohjaa AI:ta

Kun annat AI-agentille speksin promptin sijaan, agentti:

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

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

Iteratiivinen speksityö

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

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

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