Dobar Spec Coding (specifikacijski vođeno programiranje) u srži pretvara "nejasne ideje" u "precizne, provjerljive i izvršne ugovore". Nije samo pisanje dokumenta, već uspostavljanje nedvosmislenog jezika komunikacije između ljudi i AI-ja (ili među ljudima). U nastavku ću iz četiri dimenzije – struktura sadržaja specifikacije, principi pisanja, proces suradnje s AI-jem, provjera kvalitete – dati izgled dobrog spec-a.

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

Primjer testnog slučaja (ugrađen u spec)

Dobar spec najprije mora napisati testne slučajeve jer AI može na temelju njih izravno generirati jedinične testove, a nakon završetka automatski provjeriti.

2. Ključna načela pisanja spec-a (SMART varijanta)

3. Proces spec coding-a u suradnji s AI-jem

1. Čovjek piše spec (gornja struktura, posebno testne slučajeve i potpise funkcija).
2. Daj spec AI-ju u jednom dahu (nemoj dodavati zahtjeve u dijalogu, izbjegavaj 'vibe' kontaminaciju).
3. AI ispisuje kod + jedinične testove (AI mora generirati izvršne testove prema testnim slučajevima u spec-u).
4. Pokreni testove: ako svi prolaze, idi na sljedeći korak; ako ne prolaze, izmijeni spec ili izravno ispravi kod (u tom trenutku možeš ući u malu petlju, ali zabilježi promjene).
5. Ručna provjera: provjeri jesu li uvedene funkcije izvan spec-a (scope creep), provjeri sigurnost/performanse.
6. Učvrsti: predaj dokument spec-a i konačni kod zajedno u repozitorij kao trajnu dokumentaciju.

Ključna praksa: Kodificiraj spec – koristi spec.md + test_spec.py, pri čemu testna datoteka izravno dolazi iz primjera u spec-u, tako da pri naknadnim izmjenama koda samo pokreneš testove i provjeriš je li spec narušen.

4. Učinci dobrog spec-a (mogu poslužiti kao kriteriji prihvaćanja)

• Određenost: isti spec dan različitim AI-jevima (ili različitim ljudima) dovodi do sličnih implementacija.
• Testabilnost: čim se napiše kod, može se odmah automatski provjeriti 90% točnosti.
• Održivost: nakon šest mjeseci svatko tko pogleda spec može razumjeti izvornu namjeru dizajna.
• Niski komunikacijski troškovi: tijekom rasprava u timu raspravlja se samo o spec-u, ne o konkretnim redovima koda.
• Ugrađena sigurnost/kvaliteta: sigurnosni zahtjevi (poput parametriziranih upita) i rubni uvjeti navedeni su 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 istinitost e-pošte

## 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 biti u skladu s osnovnim formatom RFC 5322 (a@b.c)
- password: duljina 8-20, mora sadržavati barem jedan broj i jedno veliko slovo
- Koristiti bcrypt za šifrirano pohranjivanje, salt cost 10
- Ako se otkrije da email već postoji prije pohrane u bazu → 409

## Testni slučajevi (unos -> očekivani statusni kod + polje odgovora)
| Unos email | password | Očekivanje |
|------------|----------|------|
| 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 |

## Nefunkcionalno
- SQL mora koristiti parametrizirane upite (zaštita od injekcije)
- Zapisivanje IP adrese registracije, ne zapisivati lozinku
- Vrijeme odgovora 95% zahtjeva < 100ms (bez bcrypt)

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

Dobar Spec Coding = zapisati ljudske "projektne odluke" kao strojne "testne slučajeve + tipne potpise + ograničenja ponašanja", tako da AI samo popunjava implementaciju, a čovjek uvijek kontrolira kvalitetu i smjer.