AI serija intervjua 16: Kako bi trebao izgledati dobar spec coding?

Dobar Spec Coding (specifikacijsko programiranje) ima za cilj pretvoriti "nejasne ideje" u "precizan, provjerljiv i izvršiv ugovor". Ne radi se samo o pisanju dokumenta, već o uspostavljanju nedvosmislenog komunikacijskog jezika između ljudi i AI-ja (ili među ljudima). U nastavku ću opisati kako izgleda dobar spec kroz četiri dimenzije: struktura sadržaja specifikacije, principi pisanja, proces saradnje s AI-jem i provjera kvaliteta.

1. Standardna struktura dokumenta specifikacije (na primjeru funkcionalnog modula)

Poglavlje	Obavezni sadržaj	Primjer
1. Cilj i opseg	Jedna rečenica šta se radi, jasno šta se ne radi	"Implementirati API za registraciju korisnika, bez verifikacije e-pošte"
2. Ulazni/izlazni ugovor	Struktura podataka, tipovi, obavezna/opcionalna polja, primjeri vrijednosti	`POST /register` tijelo zahtjeva `{email: string, password: string}`, odgovor `201` ili `400` s kodom greške
3. Ponašanje i logika	Poslovna pravila, granični uvjeti, prijelazi stanja	"Dužina lozinke 8-20 znakova, najmanje jedan broj; ako email već postoji, vrati `409`"
4. Obrada grešaka	Svi mogući izuzetni scenariji i odgovarajući kodovi/poruke greške	"Neuspješno povezivanje s bazom → vrati `503`, ne otkrivaj stek"
5. Nefunkcionalni zahtjevi	Performanse (vrijeme odgovora < 200ms), sigurnost (parametrizirani upiti), evidentiranje, mogućnost praćenja	"Svi SQL upiti moraju koristiti prekompajlirane izraze; evidentiraj `email`, ali ne i `password`"
6. Testni slučajevi (ključno)	Najmanje 3 tipična unosa + 2 granična/izuzetna unosa, s očekivanim izlazom	Vidi tabelu ispod
7. Zavisnosti i ograničenja	Koje biblioteke, verzije, varijable okruženja	"Python 3.10+, FastAPI, varijabla okruženja `DB_URL`"

Primjer testnih slučajeva (ugrađeno u spec)

Scenarij	Ulaz	Očekivani izlaz
Normalna registracija	email: `a@b.com`, lozinka: `Pass1234`	`201`, vrati `user_id`
Prekratka lozinka	lozinka: `Ab1`	`400`, kod greške `WEAK_PASSWORD`
Email već postoji	isti email	`409`, kod greške `EMAIL_EXISTS`

Dobar spec prvo piše testne slučajeve, jer AI može na osnovu njih direktno generirati jedinične testove, a nakon završetka automatski ih provjeriti.

2. Ključni principi pisanja spec-a (SMART varijanta)

Princip	Objašnjenje	Protuprimjer
Precizan (Precise)	Koristi konkretne brojeve, tipove, logičke uslove; izbjegavaj "što je više moguće", "obično"	❌ "Lozinka treba biti dovoljno sigurna" → ✅ "Lozinka najmanje 8 znakova, sadrži veliko slovo, malo slovo i broj"
Provjerljiv (Verifiable)	Svaki zahtjev može se automatskim testom ili ručnom provjerom ocijeniti kao prolaz/neuspjeh	❌ "Kod treba biti elegantan" → ✅ "Ciklomatska kompleksnost funkcije ≤ 10, nema dupliciranih blokova koda"
Nedvosmislen (Unambiguous)	Isti termin ima konzistentno značenje kroz cijeli tekst; po potrebi dati rječnik pojmova	❌ "Ako korisnik ne postoji, vrati grešku" → ✅ "Korisnik ne postoji → vrati `404` i `{code: 'USER_NOT_FOUND'}`"
Potpun (Complete)	Pokriva sretni put, sve izuzetne puteve, nefunkcionalne zahtjeve	❌ Samo uspješni scenariji → ✅ Uključuje vremensko istek baze, nedovoljna ovlaštenja itd.
Atomski (Atomic)	Jedan spec opisuje samo jednu nezavisno isporučivu funkcionalnost (olakšava AI-ju da završi odjednom)	❌ Jedan spec za "cijeli sistem plaćanja" → ✅ Razbijeno na "generiranje naloga za plaćanje", "provjera potpisa pri povratnom pozivu", "povrat novca"

3. Proces Spec Codinga u saradnji s AI-jem

Čovjek piše spec (gornja struktura, posebno testne slučajeve i potpise funkcija).
Učitaj spec AI-ju odjednom (ne dodavati zahtjeve kroz dijalog kako bi se izbjegla kontaminacija vibracijom).
AI daje kod + jedinične testove (AI mora generirati izvršive testove prema testnim slučajevima iz spec-a).
Pokreni testove: ako svi prođu, idi na sljedeći korak; ako ne prođu, izmijeni spec ili direktno ispravi kod (u tom slučaju može se ući u mali ciklus, ali promjene treba zabilježiti).
Ručna provjera: provjeri da li je uvedena funkcionalnost izvan spec-a (scope creep), provjeri sigurnost/performanse.
Učvrsti: pošalji dokument spec-a i konačni kod zajedno u repozitorij kao trajnu dokumentaciju.

Ključna praksa: Spec kao kod – koristi spec.md + test_spec.py, gdje testna datoteka dolazi direktno iz primjera u spec-u, tako da naknadne izmjene koda samo pokretanjem testova potvrđuju da spec nije narušen.

4. Efekti dobrog spec-a (mogu poslužiti kao kriteriji prihvatanja)

Određenost: Isti spec dat različitim AI-jevima (ili različitim ljudima) daje slične implementacije.
Testabilnost: Po završetku koda može se odmah automatski potvrditi 90% ispravnosti.
Održivost: Nakon šest mjeseci bilo ko ko pogleda spec može razumjeti originalne dizajnerske odluke.
Niski troškovi komunikacije: Tokom timskih diskusija raspravlja se samo o spec-u, ne o konkretnim linijama koda.
Ugrađena sigurnost/kvalitet: Sigurnosni zahtjevi (poput parametriziranih upita) i granični uvjeti su navedeni u spec-u, AI ih se mora pridržavati.

5. Primjer dobrog spec-a (minimalna verzija)

# Spec: API za registraciju korisnika

## Opseg
- Prima email, password
- Ne šalje verifikacijski email, ne provjerava stvarnost emaila

## Ugovor
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" }

## Ponašanje
- email mora odgovarati osnovnom formatu RFC 5322 (a@b.c)
- password: dužina 8-20, najmanje jedan broj i jedno veliko slovo
- Koristi bcrypt za šifrirano pohranjivanje, cijena soli 10
- Ako se prije pohranjivanja u bazu otkrije da email već postoji → 409

## Testni slučajevi (ulaz -> očekivani statusni kod + polja odgovora)
| Ulazni email | Lozinka | Očekivano |
|--------------|---------|-----------|
| test@x.com   | Pass1234 | 201, user_id postoji |
| test@x.com   | pass     | 400, INVALID_PASSWORD |
| bad          | Pass1234 | 400, INVALID_EMAIL |
| (email koji već postoji) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Nefunkcionalni zahtjevi
- SQL upiti moraju koristiti parametrizirane upite (zaštita od injekcija)
- Evidentiranje: zabilježi IP izvor registracije, ne bilježi lozinku
- Vrijeme odgovora: 95% zahtjeva < 100ms (bez bcrypt-a)

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

Dobar Spec Coding = pretvoriti ljudske "dizajnerske odluke" u mašinske "testne slučajeve + tipski potpis + ograničenja ponašanja", tako da AI samo popunjava implementaciju, dok čovjek uvijek kontrolira kvalitet i smjer.