AI serija intervju 16: Kako treba da izgleda dobro spec kodiranje?

Dobro Spec kodiranje (specifikacijom vođeno programiranje) suštinski pretvara „nejasne ideje“ u „precizne, proverljive i izvršive ugovore“. Nije samo pisanje dokumenta, već uspostavljanje nedvosmislene komunikacije između ljudi i AI (ili među ljudima). U nastavku ću dati prikaz dobrog spec-a iz četiri dimenzije: struktura sadržaja specifikacije, principi pisanja, tok saradnje sa AI, provera kvaliteta.

1. Standardna struktura specifikacije (na primeru funkcionalnog modula)

Poglavlje	Obavezni sadržaj	Primer
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. Ulaz/izlaz ugovor	Struktura podataka, tip, obavezna/opciona polja, primer vrednosti	`POST /register` telo zahteva `{email: string, password: string}`, odgovor `201` ili `400` sa kodom greške
3. Ponašanje i logika	Poslovna pravila, granični uslovi, prelazi stanja	„Dužina lozinke 8-20 karaktera, najmanje jedan broj; ako email već postoji vrati `409`“
4. Obrada grešaka	Svi mogući izuzetni scenariji i odgovarajući kodovi/poruke grešaka	„Neuspešna konekcija sa bazom → vrati `503`, ne izlagati stek“
5. Nefunkcionalni zahtevi	Performanse (vreme odgovora < 200ms), sigurnost (parametrizovani upiti), evidentiranje, mogućnost praćenja	„Svi SQL upiti moraju koristiti prekompajlirane; evidentirati `email` ali ne i `password`“
6. Test slučajevi (ključno)	Najmanje 3 tipična unosa + 2 granična/izuzetna unosa, dati očekivani izlaz	Pogledati tabelu ispod
7. Zavisnosti i ograničenja	Koje biblioteke se koriste, verzije, promenljive okruženja	„Python 3.10+, FastAPI, promenljiva okruženja `DB_URL`“

Primer test slučajeva (ugrađen u spec)

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

Dobar Spec prvo piše test slučajeve, jer AI na osnovu njih može direktno da generiše jedinične testove, a nakon implementacije automatski da ih proveri.

2. Osnovni principi pisanja Spec-a (SMART varijanta)

Princip	Objašnjenje	Anti-primer
Precizan (Precise)	Koristiti konkretne brojeve, tipove, bool uslove; izbegavati „koliko je moguće“, „obično“	❌ „Lozinka treba da bude dovoljno sigurna“ → ✅ „Lozinka najmanje 8 karaktera, sadrži veliko slovo, malo slovo i broj“
Proverljiv (Verifiable)	Svaki zahtev se može automatskim testom ili ručnom proverom oceniti kao ispunjen/neispunjen	❌ „Kod treba da bude elegantan“ → ✅ „Ciklomatska složenost funkcije ≤ 10, bez dupliranih blokova koda“
Nedvosmislen (Unambiguous)	Isti termin ima konzistentno značenje kroz ceo tekst; po potrebi dati rečnik	❌ „Ako korisnik ne postoji, vrati grešku“ → ✅ „Korisnik ne postoji → vrati `404` i `{code: 'USER_NOT_FOUND'}`“
Potpun (Complete)	Pokriva srećan put, sve izuzetne puteve i nefunkcionalne zahteve	❌ Samo napisan uspešni scenario → ✅ Uključuje timeout baze, nedovoljne privilegije itd.
Atomiziran (Atomic)	Jedan spec opisuje samo jednu funkcionalnost koja se može samostalno isporučiti (olakšava AI da završi odjednom)	❌ Koristiti jedan spec za „celokupan sistem plaćanja“ → ✅ Razdvojiti na „generisanje naloga za plaćanje“, „verifikaciju potpisa povratnog poziva“, „povraćaj novca“

3. Spec kodiranje u saradnji sa AI

Čovek piše spec (gornja struktura, posebno dobro napisati test slučajeve i potpise funkcija).
Spec se daje AI u jednom dahu (ne dodavati zahteve kroz dijalog, izbegavati „vibe“ kontaminaciju).
AI izlazni kod + jedinični testovi (AI mora da generiše izvršive testove prema test slučajevima iz spec-a).
Pokrenuti testove: Ako svi prođu, preći na sledeći korak; ako ne prođu, izmeniti spec ili direktno ispraviti kod (tada se može ući u mali ciklus, ali promene se beleže).
Pregled od strane čoveka: Proveriti da li postoji funkcionalnost van spec-a (scope creep), proveriti sigurnost/performanse.
Fiksiranje: Spec dokument i finalni kod zajedno se postavljaju u repozitorijum kao trajna dokumentacija.

Ključna praksa: Spec kao kod – koristiti spec.md + test_spec.py, pri čemu test fajl direktno dolazi iz primera u spec-u, tako da naknadna izmena koda samo zahteva pokretanje testova kako bi se proverilo da li je spec narušen.

4. Efekti dobrog Spec-a (mogu poslužiti kao kriterijumi prihvatanja)

Determinističnost: Isti spec dat različitim AI ili različitim ljudima daje slične implementacije.
Testabilnost: Nakon pisanja koda, odmah se automatski može proveriti 90% tačnosti.
Održivost: Posle pola godine bilo ko može pogledati spec i razumeti prvobitne dizajnerske namere.
Niska komunikaciona cena: U timskim diskusijama razmatra se samo spec, ne i konkretni redovi koda.
Ugrađena sigurnost/kvalitet: Sigurnosni zahtevi (npr. parametrizovani upiti) i granični uslovi su zapisani u spec-u, AI se mora pridržavati.

5. Primer dobrog Spec-a (minimalna verzija)

# Spec: API za registraciju korisnika

## Opseg
- Prima email, password
- Ne šalje verifikacioni email, ne proverava stvarnost email-a

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

## Ponašanje
- email mora zadovoljavati osnovni RFC 5322 format (a@b.c)
- password: dužina 8-20, najmanje jedan broj i jedno veliko slovo
- Čuvati šifrovano sa bcrypt, sol cost 10
- Ako se pre čuvanja u bazi otkrije da email već postoji → 409

## Test slučajevi (ulaz -> očekivani status kod + polje odgovora)
| Ulaaz email | password | Očekivano |
|-------------|----------|-----------|
| test@x.com | Pass1234  | 201, user_id postoji |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (već postojeći email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Nefunkcionalni
- SQL mora koristiti parametrizovane upite (sprečiti injekciju)
- Evidentirati IP izvor registracije, ne evidentirati lozinku
- Vreme odgovora 95% zahteva < 100ms (bez bcrypt)

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

Dobro Spec kodiranje = pretvaranje ljudskih „dizajnerskih odluka“ u mašinske „test slučajeve + tipizirane potpise + ograničenja ponašanja“, tako da AI samo popunjava implementaciju, dok čovek uvek kontroliše kvalitet i smer.