AI-sarjan haastattelu 16: Millainen on hyvä spec-koodaus?

Hyvä Spec-koodaus (spesifikaatiovetoinen ohjelmointi) muuttaa "epämääräiset ajatukset" täsmällisiksi, todennettaviksi ja toteutettaviksi sopimuksiksi. Se ei ole vain dokumentti, vaan joukko yksiselitteisiä viestintävälineitä ihmisen ja AI:n (tai ihmisten) välillä. Alla käsittelen neljää ulottuvuutta: spesifikaation sisältörakenne, kirjoitusperiaatteet, AI-yhteistyöprosessi ja laadunvarmistus, ja annan kuvan hyvästä specistä.

1. Spesifikaatiodokumentin standardirakenne (esimerkkinä toimintomoduuli)

Luku	Pakollinen sisältö	Esimerkki
1. Tavoite ja laajuus	Yksi lause siitä, mitä tehdään, ja selkeästi mitä ei tehdä	"Toteutetaan käyttäjien rekisteröinnin API, ei sisällä sähköpostin vahvistusta"
2. Syöte/tuloste -sopimus	Tietorakenne, tyypit, pakolliset/valinnaiset kentät, esimerkkiarvot	`POST /register` -pyyntörunko `{email: string, password: string}`, vastaus `201` tai `400` virhekoodilla
3. Käyttäytyminen ja logiikka	Liiketoimintasäännöt, raja-arvot, tilasiirtymät	"Salasanan pituus 8-20 merkkiä, vähintään yksi numero; jos sähköposti on jo olemassa, palauta `409`"
4. Virheiden käsittely	Kaikki mahdolliset poikkeustilanteet ja niitä vastaavat virhekoodit/viestit	"Tietokantayhteys epäonnistuu → palauta `503`, älä paljasta pinoa"
5. Ei-toiminnalliset vaatimukset	Suorituskyky (vastausaika < 200 ms), turvallisuus (parametrisoidut kyselyt), lokit, havaittavuus	"Kaikki SQL:t on esikäännettävä; kirjaa `email` mutta älä `password`"
6. Testitapaukset (kriittinen)	Vähintään 3 tyypillistä syötettä + 2 raja/poikkeussyötettä, odotettu tulos	Katso alla oleva taulukko
7. Riippuvuudet ja rajoitteet	Mitä kirjastoja, versioita, ympäristömuuttujia käytetään	"Python 3.10+, FastAPI, ympäristömuuttuja `DB_URL`"

Esimerkki testitapauksista (sisällytettynä spec:iin)

Skenaario	Syöte	Odotettu tulos
Normaali rekisteröinti	email: `a@b.com`, salasana: `Pass1234`	`201`, palauttaa `user_id`
Salasana liian lyhyt	salasana: `Ab1`	`400`, virhekoodi `WEAK_PASSWORD`
Sähköposti jo olemassa	sama email	`409`, virhekoodi `EMAIL_EXISTS`

Hyvä spec kirjoitetaan ensin testitapauksineen, koska AI voi niiden perusteella luoda suoraan yksikkötestit ja automaattisesti varmistaa ne.

2. Specin kirjoittamisen perusperiaatteet (SMART-muunnelma)

Periaate	Selitys	Vastaesimerkki
Täsmällinen (Precise)	Käytä konkreettisia lukuja, tyyppejä, loogisia ehtoja; vältä "mahdollisimman", "yleensä"	❌ "Salasanan on oltava riittävän turvallinen" → ✅ "Salasanassa vähintään 8 merkkiä, sisältää ison kirjaimen, pienen kirjaimen ja numeron"
Todennettava (Verifiable)	Jokainen vaatimus voidaan tarkistaa automaattisesti tai manuaalisesti hyväksytyksi/hylätyksi	❌ "Koodin on oltava tyylikästä" → ✅ "Funktion syklomaattinen kompleksisuus ≤ 10, ei toistuvia koodilohkoja"
Yksiselitteinen (Unambiguous)	Sama termi tarkoittaa samaa koko tekstissä; tarvittaessa määrittele sanasto	❌ "Jos käyttäjää ei ole, palauta virhe" → ✅ "Käyttäjää ei ole → palauta `404` ja `{code: 'USER_NOT_FOUND'}`"
Täydellinen (Complete)	Kattaa onnellisen polun, kaikki poikkeuspolut ja ei-toiminnalliset vaatimukset	❌ Vain onnistuneet skenaariot → ✅ Sisältää tietokannan aikakatkaisun, oikeuksien puutteen jne.
Atomi (Atomic)	Yksi spec kuvaa vain yhtä itsenäisesti toimitettavaa toimintoa (jotta AI voi tehdä sen kerralla)	❌ Yksi spec "koko maksujärjestelmälle" → ✅ Jaetaan "maksutapahtuman luonti", "takaisinkutsun allekirjoituksen tarkistus", "hyvitys"

3. Spec-koodausprosessi AI:n kanssa yhteistyössä

Ihminen kirjoittaa specin (yllä oleva rakenne, erityisesti testitapaukset ja funktioiden allekirjoitukset).
Spec syötetään AI:lle kerralla (ei keskustelumuotoisia lisäyksiä, jotta vältetään "vibe"-saastuminen).
AI tuottaa koodin + yksikkötestit (AI:n on noudatettava specin testitapauksia ja luotava suoritettavia testejä).
Testien ajaminen: Jos kaikki menevät läpi, siirry seuraavaan vaiheeseen; jos eivät, muuta spec:iä tai korjaa koodi suoraan (pieni silmukka on sallittu, mutta muutokset kirjattava).
Ihmisen tarkistus: Tarkistetaan, onko lisätty specin ulkopuolisia toimintoja (scope creep), tarkistetaan turvallisuus ja suorituskyky.
Vakiointi: Spec-dokumentti ja lopullinen koodi tallennetaan yhdessä repositorioon pysyväksi dokumentaatioksi.

Keskeinen käytäntö: Specin koodaus — käytä spec.md + test_spec.py, jossa testitiedosto tulee suoraan specin esimerkeistä, jotta myöhemmät koodimuutokset voidaan validoida ajamalla testit.

4. Hyvän specin tuottamat hyödyt (voi käyttää hyväksymiskriteereinä)

Determinismi: Sama spec tuottaa eri AI:lle (tai eri henkilöille) samankaltaiset toteutukset.
Testattavuus: Koodin valmistuttua voidaan automaattisesti todentaa 90 % oikeellisuudesta.
Ylläpidettävyys: Puolen vuoden päästä kuka tahansa näkee specistä alkuperäiset suunnittelupäätökset.
Pienet viestintäkustannukset: Tiimikeskustelussa käsitellään vain spec:iä, ei yksittäisiä koodirivejä.
Sisäänrakennettu turvallisuus/laatu: Turvallisuusvaatimukset (kuten parametrisoidut kyselyt) ja raja-arvot kirjoitetaan spec:iin, AI:n on noudatettava niitä.

5. Esimerkki hyvästä specistä (minimiversio)

# Spec: Käyttäjärekisteröinnin API

## Laajuus
- Vastaanottaa email ja salasana
- Ei lähetä vahvistussähköpostia, ei tarkista sähköpostin oikeellisuutta

## Sopimus
POST /register
Content-Type: application/json
Pyyntö: { "email": string, "password": string }
Vastaus 201: { "user_id": string }
Vastaus 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Vastaus 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Käyttäytyminen
- email on oltava RFC 5322 -perusmuodossa (a@b.c)
- salasana: pituus 8-20, vähintään yksi numero ja yksi iso kirjain
- Käytä bcrypt-salausta, suolakustannus 10
- Jos ennen tietokantaan tallentamista havaitaan, että email on jo olemassa → 409

## Testitapaukset (syöte -> odotettu tilakoodi + vastauskenttä)
| Syöte email | salasana | Odotettu |
|-------------|----------|----------|
| test@x.com  | Pass1234 | 201, user_id on olemassa |
| test@x.com  | pass     | 400, INVALID_PASSWORD |
| bad         | Pass1234 | 400, INVALID_EMAIL |
| (jo olemassa oleva email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Ei-toiminnalliset vaatimukset
- SQL on käytettävä parametrisoituja kyselyitä (injektion estämiseksi)
- Lokitetaan rekisteröinnin lähde-IP, ei salasanaa
- Vastausaika 95 %:ssa pyynnöistä < 100 ms (ilman bcryptiä)

## Riippuvuudet
- Python 3.10+, FastAPI, bcrypt, asyncpg

Hyvä Spec-koodaus = ihmisen "suunnittelupäätökset" muutetaan koneen "testitapauksiksi + tyyppiallekirjoituksiksi + käyttäytymisrajoituksiksi", jolloin AI vastaa vain toteutuksen täyttämisestä, ja ihminen hallitsee laatua ja suuntaa.