AI seeria intervjuu 16: Milline peaks olema hea spec coding?

Hea Spec Coding (spetsifikatsioonipõhine programmeerimine) keskendub sellele, et muuta "hägused ideed" "täpseteks, kontrollitavateks ja täidetavateks lepinguteks". See ei ole lihtsalt dokumendi kirjutamine, vaid selge suhtluskeel inimeste ja AI (või inimese ja inimese) vahel, mis välistab mitmetimõistmise. Allpool selgitan, milline on hea spetsifikatsioon, lähtudes neljast mõõtmest: spetsifikatsiooni sisu struktuur, kirjutamispõhimõtted, koostöö AI-ga ja kvaliteedikontroll.

1. Spetsifikatsioonidokumendi standardstruktuur (näide: funktsioonimoodul)

Peatükk	Kohustuslik sisu	Näide
1. Eesmärk ja ulatus	Üks lause, mis ütleb, mida tehakse, ja selgelt, mida ei tehta	"Rakendame kasutaja registreerimise API-d, ei hõlma e-posti kinnitust"
2. Sisend/väljund leping	Andmestruktuurid, tüübid, kohustuslikud/vabatahtlikud väljad, näidisväärtused	`POST /register` päringu keha `{email: string, password: string}`, vastus `201` või `400` koos veakoodiga
3. Käitumine ja loogika	Ärireeglid, piirtingimused, olekumuutused	"Parooli pikkus 8-20 tähemärki, peab sisaldama vähemalt ühte numbrit; kui e-post on juba olemas, tagasta `409`"
4. Veakäsitlus	Kõik võimalikud erandolukorrad ja vastavad veakoodid/sõnumid	"Andmebaasiühenduse ebaõnnestumine → tagasta `503`, ära paljasta virnakoopiat"
5. Mitterfunktsionaalsed nõuded	Jõudlus (reageerimisaeg < 200 ms), turvalisus (parametriseeritud päringud), logimine, jälgitavus	"Kõik SQL-päringud peavad kasutama eelkompileeritud päringuid; logi `email`, kuid ära logi `password`"
6. Testjuhtumid (oluline)	Vähemalt 3 tüüpilist sisendit + 2 piiri/erandlikku sisendit, koos oodatava väljundiga	Vaata allolevat tabelit
7. Sõltuvused ja piirangud	Milliseid teeke, versioone, keskkonnamuutujaid kasutatakse	"Python 3.10+, FastAPI, keskkonnamuutuja `DB_URL`"

Testjuhtumite näide (spetsifikatsiooni sees)

Stsenaarium	Sisend	Oodatav väljund
Tavaline registreerimine	email: `a@b.com`, pwd: `Pass1234`	`201`, tagasta `user_id`
Parool liiga lühike	pwd: `Ab1`	`400`, veakood `WEAK_PASSWORD`
E-post juba olemas	sama email nagu eelmine	`409`, veakood `EMAIL_EXISTS`

Hea spetsifikatsioon peab esmalt kirja panema testjuhtumid, sest AI saab nende põhjal otse genereerida ühiktestid, mis pärast täitmist automaatselt kontrollivad.

2. Spetsifikatsiooni kirjutamise põhiprintsiibid (SMART-i variant)

Põhimõte	Selgitus	Vastunäide
Täpne (Precise)	Kasuta konkreetseid numbreid, tüüpe, tõeväärtustingimusi; väldi "võimalikult", "tavaliselt"	❌ "Parool peab olema piisavalt turvaline" → ✅ "Parool peab olema vähemalt 8 tähemärki pikk, sisaldama suurt ja väikest tähte ning numbrit"
Kontrollitav (Verifiable)	Iga nõue peab olema automaattesti või käsitsi kontrolli abil hinnatav läbimiseks/ebaõnnestumiseks	❌ "Kood peab olema elegantne" → ✅ "Funktsiooni tsüklomaatiline keerukus ≤ 10, dubleerivaid koodiplokke pole"
Ühemõtteline (Unambiguous)	Sama termin peab kogu dokumendis tähendama sama asja; vajadusel lisa sõnastik	❌ "Kui kasutajat pole, tagasta viga" → ✅ "Kasutajat pole → tagasta `404` ja `{code: 'USER_NOT_FOUND'}"`
Täielik (Complete)	Hõlma rõõmutee, kõik eranditeed ja mittefunktsionaalsed nõuded	❌ Kirjutatud ainult edukad stsenaariumid → ✅ Hõlma ka andmebaasi ajalõpp, ebapiisavad õigused jne
Aatomiline (Atomic)	Üks spetsifikatsioon kirjeldab ainult ühte sõltumatult tarnitavat funktsiooni (võimaldab AI-l korraga lõpetada)	❌ Üks spetsifikatsioon "kogu maksesüsteemile" → ✅ Tükelda: "maksekorralduse loomine", "tagasikutsumise allkirja kontroll", "tagasimakse"

3. Spec Coding protsess AI-ga koostöös

Inimene kirjutab spetsifikatsiooni (ülaltoodud struktuur, eriti testjuhtumid ja funktsioonide signatuurid).
Anna spetsifikatsioon AI-le korraga (ära lisa dialoogiliselt uusi nõudeid, et vältida "vibe" saastumist).
AI väljastab koodi ja ühiktestid (AI peab spetsifikatsioonis olevate testjuhtumite põhjal genereerima teostatavad testid).
Käivita testid: kui kõik läbivad, liigu järgmisse sammu; kui mitte, muuda spetsifikatsiooni või paranda koodi otse (võib minna väikesesse tsüklisse, kuid salvesta muudatused).
Inimese järelkontroll: kontrolli, kas lisandus spetsifikatsiooniväliseid funktsioone (scope creep), kontrolli turvalisust/jõudlust.
Kinnista: lisa spetsifikatsioonidokument ja lõplik kood koos hoidlasse alalise dokumendina.

Oluline praktika: Spetsifikatsiooni koodistamine – kasuta spec.md + test_spec.py, kus testifail pärineb otse spetsifikatsioonis olevatest näidetest; hilisem koodimuutus nõuab testide käivitamist, et kontrollida spetsifikatsiooni rikkumist.

4. Hea spetsifikatsiooni mõju (võib kasutada vastuvõtukriteeriumidena)

Deterministlik: Sama spetsifikatsiooniga erinevad AI-d (või inimesed) annavad sarnase teostuse.
Testitav: Kohe pärast koodi kirjutamist saab automaatselt kontrollida 90% õigsust.
Hooldatav: Pool aastat hiljem näeb igaüks spetsifikatsiooni ja mõistab algseid disainiotsuseid.
Väike suhtluskulu: Meeskonnas arutatakse ainult spetsifikatsiooni, mitte konkreetseid koodiridu.
Turvalisus/kvaliteet sisseehitatud: Turvanõuded (nt parametriseeritud päringud) ja piirtingimused on spetsifikatsioonis kirjas, AI peab neid järgima.

5. Hea spetsifikatsiooni näide (minimaalne versioon)

# Spec: Kasutaja registreerimise API

## Ulatus
- Võtab vastu emaili ja parooli
- Ei saada kinnitusmeili, ei kontrolli e-posti autentsust

## Leping
POST /register
Content-Type: application/json
Päring: { "email": string, "password": string }
Vastus 201: { "user_id": string }
Vastus 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Vastus 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Käitumine
- email peab vastama RFC 5322 põhivormingule (a@b.c)
- parool: pikkus 8-20, peab sisaldama vähemalt ühte numbrit ja ühte suurtähte
- salvestamiseks kasuta bcrypt-i, soola kulu 10
- kui enne andmebaasi salvestamist avastatakse, et e-post on juba olemas → 409

## Testjuhtumid (sisend -> oodatav olekukood+vastuse väli)
| Sisend email | parool | Oodatav |
|-------------|--------|---------|
| test@x.com | Pass1234 | 201, user_id on olemas |
| test@x.com | pass | 400, INVALID_PASSWORD |
| bad | Pass1234 | 400, INVALID_EMAIL |
| (juba olemasolev e-post) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Mittefunktsionaalsed nõuded
- SQL peab kasutama parametriseeritud päringuid (sissepritse vältimiseks)
- Logi registreerimise allika IP, ära logi parooli
- 95% päringutest reageerivad < 100 ms (ilma bcrypt-ita)

## Sõltuvused
- Python 3.10+, FastAPI, bcrypt, asyncpg

Hea Spec Coding = inimese "disainiotsuste" muutmine masina "testjuhtumiteks + tüübisignatuurideks + käitumispiiranguteks", lastes AI-l ainult teostus täita, samal ajal kui inimene hoiab kontrolli kvaliteedi ja suuna üle.