AI serija intervjujev 16: Kakšno naj bo dobro spec kodiranje?

Dobro Spec kodiranje (specifikacijsko vodenje programiranja) ima jedro v tem, da 'nejasne zamisli' spremeni v 'natančne, preverljive in izvršljive pogodbe'. Ne gre samo za pisanje dokumenta, ampak za vzpostavitev nedvoumnega komunikacijskega jezika med ljudmi in AI (ali med ljudmi). Spodaj bom iz štirih dimenzij – vsebinske strukture specifikacij, načel pisanja, procesa sodelovanja z AI in preverjanja kakovosti – podal, kako izgleda dobra spec.

1. Standardna struktura dokumenta specifikacije (na primeru funkcijskega modula)

Poglavje	Obvezna vsebina	Primer
1. Namen in obseg	V enem stavku pove, kaj počne, jasno česa ne počne	"Implementira API za registracijo uporabnika, ne vključuje potrditve e-pošte"
2. Vhodno/izhodna pogodba	Podatkovna struktura, tip, obvezni/neobvezni polja, vzorčne vrednosti	`POST /register` telo zahteve `{email: string, password: string}`, odziv `201` ali `400` s kodo napake
3. Vedenje in logika	Poslovna pravila, mejni pogoji, prehodi stanj	"Dolžina gesla 8-20 znakov, vsaj ena številka; če e-pošta že obstaja, vrni `409`"
4. Obdelava napak	Vsi možni izjemni scenariji in pripadajoče kode napak/sporočila	"Neuspeh povezave z bazo podatkov → vrni `503`, ne razkrivaj sklada"
5. Nefunkcijske zahteve	Zmogljivost (odzivni čas < 200ms), varnost (parametrizirani poizvedbi), dnevniki, opazljivost	"Vsi SQL-i morajo uporabljati predpripravljene stavke; beleži `email`, ne beleži `password`"
6. Testni primeri (ključni)	Vsaj 3 tipični vnosi + 2 mejna/izjemna vnosa, podaj pričakovane izhode	glej spodnjo tabelo
7. Odvisnosti in omejitve	Katere knjižnice, različice, okoljske spremenljivke	`Python 3.10+`, `FastAPI`, okoljska spremenljivka `DB_URL`

Primeri testnih primerov (vgrajeni v spec)

Scenarij	Vhod	Pričakovani izhod
Normalna registracija	email: `a@b.com`, pwd: `Pass1234`	`201`, vrni `user_id`
Prekratko geslo	pwd: `Ab1`	`400`, koda napake `WEAK_PASSWORD`
E-pošta že obstaja	enak email	`409`, koda napake `EMAIL_EXISTS`

Dobra spec mora najprej napisati testne primere, ker lahko AI na njihovi podlagi neposredno generira enotske teste in jih po končanju samodejno preveri.

2. Osrednja načela pisanja spec (različica SMART)

Načelo	Razlaga	Protiprimer
Natančnost (Precise)	Uporabljaj konkretne številke, tipe, boolove pogoje; izogibaj se 'kolikor je mogoče', 'običajno'	❌ 'Geslo naj bo dovolj varno' → ✅ 'Geslo naj ima vsaj 8 znakov, vključuje velike, male črke in številke'
Preverljivost (Verifiable)	Vsako zahtevo je mogoče s samodejnim testom ali ročnim pregledom oceniti kot uspešno/neuspešno	❌ 'Koda naj bo elegantna' → ✅ 'Ciklomatska kompleksnost funkcije ≤ 10, brez podvojenih blokov kode'
Nedvoumnost (Unambiguous)	Isti izraz ima v celotnem besedilu enak pomen; po potrebi podaj slovarček	❌ 'Če uporabnik ne obstaja, vrni napako' → ✅ 'Uporabnik ne obstaja → vrni `404` in `{code: 'USER_NOT_FOUND'}`'
Popolnost (Complete)	Zajema srečno pot, vse izjemne poti in nefunkcijske zahteve	❌ Napisani so samo uspešni scenariji → ✅ Vključuje časovno omejitev baze, pomanjkanje dovoljenj itd.
Atomičnost (Atomic)	Ena spec opisuje samo eno samostojno dobavljivo funkcijsko točko (za lažje dokončanje z AI)	❌ Uporaba ene spec za 'celoten plačilni sistem' → ✅ Razdelitev na 'ustvari plačilni nalog', 'preveri podpis povratnega klica', 'povračilo'

3. Postopek spec kodiranja pri sodelovanju z AI

Človek napiše spec (zgornja struktura, zlasti dobro napiše testne primere in podpise funkcij).
Spec v celoti podaj AI-ju (ne dodajaj zahtev v pogovornem načinu, da se izogneš vibracijski kontaminaciji).
AI izda kodo + enotske teste (AI mora generirati izvršljive teste v skladu s testnimi primeri v spec).
Zaženi teste: če vsi uspešni, pojdi na naslednji korak; če ne, spremeni spec ali neposredno popravi kodo (takrat lahko vstopiš v majhno zanko, vendar zabeleži spremembe).
Ročni pregled: preveri, ali so uvedene funkcije zunaj spec (scope creep), preveri varnost/zmogljivost.
Utrdi: oddaj dokument spec in končno kodo skupaj v repozitorij kot trajni dokument.

Ključna praksa: Spec kodifikacija – uporabi spec.md + test_spec.py, kjer testna datoteka izhaja neposredno iz primerov v spec, tako da je pri kasnejšem spreminjanju kode potrebno samo zagnati teste, da preveriš, ali je spec kršen.

4. Učinki dobre spec (lahko služijo kot merila za sprejemljivost)

Določnost: Ista spec različnim AI (ali različnim ljudem) daje podobne implementacije.
Testabilnost: Takoj po pisanju kode je mogoče samodejno potrditi 90 % pravilnosti.
Vzdržljivost: Po pol leta vsak, ki pogleda spec, razume prvotne namere oblikovanja.
Nizki stroški komunikacije: Pri ekipnih razpravah se razpravlja samo o spec, ne o posameznih vrsticah kode.
Vgrajena varnost/kakovost: Varnostne zahteve (kot so parametrizirani poizvedbi) in mejni pogoji so zapisani v spec, AI jih mora upoštevati.

5. Primer dobre spec (minimalna različica)

# Spec: API za registracijo uporabnika

## Obseg
- Sprejema email, password
- Ne pošilja potrditvenega e-poštnega sporočila, ne preverja resničnosti e-pošte

## Pogodba
POST /register
Content-Type: application/json
Request: { "email": string, "password": string }
Response 201: { "user_id": string }
Response 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Response 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Vedenje
- email mora ustrezati osnovni obliki RFC 5322 (a@b.c)
- password: dolžina 8-20, vsaj ena številka in ena velika črka
- Uporabi bcrypt za šifriranje shranjevanja, stroški soli 10
- Če je email že obstaja pred shranjevanjem v bazo → 409

## Testni primeri (vhod -> pričakovana statusna koda + polje odziva)
| Vhod email | password | Pričakovano |
|------------|----------|-------------|
| test@x.com | Pass1234  | 201, user_id obstaja |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (že obstajajoč email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Nefunkcijske zahteve
- SQL mora uporabljati parametrizirane poizvedbe (preprečevanje vbrizgavanja)
- Dnevnik beleži IP izvora registracije, ne beleži gesla
- Odzivni čas 95 % zahtev < 100 ms (brez bcrypt)

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

Dobro spec kodiranje = človekove 'oblikovalske odločitve' zapiši kot strojne 'testne primere + tipne podpise + vedenjske omejitve', tako da AI skrbi samo za implementacijo, medtem ko človek vedno nadzoruje kakovost in smer.