Séria AI rozhovorov 16: Ako by malo vyzerať dobré spec coding?

Dobré Spec Coding (špecifikácia riadená kódovaním) má jadro v premene „nejasných nápadov“ na „presné, overiteľné a vykonateľné zmluvy“. Nejde len o písanie dokumentu, ale o vytvorenie jednoznačného komunikačného jazyka medzi človekom a AI (alebo medzi ľuďmi). Nižšie popíšem podobu dobrej špecifikácie zo štyroch dimenzií: štruktúra obsahu špecifikácie, princípy písania, kolaboračný proces s AI a overenie kvality.

1. Štandardná štruktúra špecifikačného dokumentu (na príklade funkčného modulu)

Sekcia	Povinný obsah	Príklad
1. Cieľ a rozsah	Jedna veta opisujúca, čo sa robí, a jasne uvádzajúca čo sa nerobí	„Implementovať API na registráciu používateľa, bez overenia emailu“
2. Vstupný/výstupný kontrakt	Dátová štruktúra, typy, povinné/voliteľné polia, príklady hodnôt	`POST /register` telo požiadavky `{email: string, password: string}`, odpoveď `201` alebo `400` s chybovým kódom
3. Správanie a logika	Obchodné pravidlá, hraničné podmienky, prechody stavov	„Dĺžka hesla 8–20 znakov, musí obsahovať aspoň jednu číslicu; ak email už existuje, vrátiť `409`“
4. Spracovanie chýb	Všetky možné výnimočné scenáre a zodpovedajúce chybové kódy/správy	„Zlyhanie pripojenia k databáze → vrátiť `503`, neodhaliť zásobník“
5. Nefunkčné požiadavky	Výkon (odozva < 200 ms), bezpečnosť (parametrické dotazy), logovanie, pozorovateľnosť	„Všetky SQL musia používať predpripravené dotazy; zaznamenávať `email`, ale nie `password`“
6. Testovacie prípady (kľúčové)	Aspoň 3 typické vstupy + 2 hraničné/výnimočné vstupy s očakávanými výstupmi	Pozri tabuľku nižšie
7. Závislosti a obmedzenia	Aké knižnice, verzie, premenné prostredia	„Python 3.10+, FastAPI, premenná prostredia `DB_URL`“

Príklad testovacích prípadov (vložených do špecifikácie)

Scenár	Vstup	Očakávaný výstup
normálna registrácia	email: `a@b.com`, heslo: `Pass1234`	`201`, vráti `user_id`
príliš krátke heslo	heslo: `Ab1`	`400`, chybový kód `WEAK_PASSWORD`
email už existuje	rovnaký email	`409`, chybový kód `EMAIL_EXISTS`

Dobrá špecifikácia najprv napíše testovacie prípady, pretože AI podľa nich môže priamo vygenerovať unit testy, ktoré sa po dokončení automaticky overia.

2. Jadrové princípy písania špecifikácie (SMART variant)

Princíp	Vysvetlenie	Protipríklad
Presné (Precise)	Používať konkrétne čísla, typy, boolovské podmienky; vyhýbať sa „pokiaľ možno“, „zvyčajne“	❌ „Heslo musí byť dostatočne bezpečné“ → ✅ „Heslo musí mať aspoň 8 znakov, obsahovať veľké, malé písmeno a číslicu“
Overiteľné (Verifiable)	Každá požiadavka musí byť rozhodnuteľná ako splnená/nesplnená pomocou automatických testov alebo manuálnej kontroly	❌ „Kód musí byť elegantný“ → ✅ „Cyklická zložitosť funkcie ≤ 10, žiadne duplicitné bloky kódu“
Jednoznačné (Unambiguous)	Rovnaký pojem má konzistentný význam v celom texte; v prípade potreby uviesť slovník	❌ „Ak používateľ neexistuje, vrátiť chybu“ → ✅ „Používateľ neexistuje → vrátiť `404` a `{code: 'USER_NOT_FOUND'}`“
Kompletné (Complete)	Pokryť happy path, všetky výnimočné cesty a nefunkčné požiadavky	❌ Iba úspešné scenáre → ✅ Zahrnúť timeout databázy, nedostatočné oprávnenia atď.
Atomické (Atomic)	Jedna špecifikácia opisuje len jeden nezávisle dodateľný funkčný bod (aby AI dokončila naraz)	❌ Použiť jednu špecifikáciu na „celý platobný systém“ → ✅ Rozdeliť na „vygenerovať platobný príkaz“, „overiť podpis pri callbacku“, „refundácia“

3. Proces Spec Coding pri spolupráci s AI

Človek napíše špecifikáciu (vyššie uvedená štruktúra, najmä testovacie prípady a signatúry funkcií).
Špecifikáciu podá AI naraz (nevyužívať dialógové dopĺňanie požiadaviek, aby sa predišlo kontaminácii atmosférou).
AI vygeneruje kód + unit testy (AI musí podľa testovacích prípadov v špecifikácii vytvoriť spustiteľné testy).
Spustenie testov: Ak všetky prejdú, prejsť na ďalší krok; ak nie, upraviť špecifikáciu alebo priamo opraviť kód (vtedy možno vstúpiť do malého cyklu, ale treba zaznamenať zmeny).
Manuálna revízia: Skontrolovať, či neboli pridané funkcie mimo špecifikácie (scope creep), skontrolovať bezpečnosť/výkon.
Ustálenie: Špecifikačný dokument a finálny kód uložiť spolu do repozitára ako trvalú dokumentáciu.

Kľúčová praktika: Kodifikácia špecifikácie – použiť spec.md + test_spec.py, kde testovací súbor priamo pochádza z príkladov v špecifikácii; pri neskorších úpravách kódu stačí spustiť testy na overenie, či špecifikácia nie je porušená.

4. Efekty dobrej špecifikácie (môžu slúžiť ako akceptačné kritériá)

Deterministickosť: Rovnaká špecifikácia vedie k podobnej implementácii u rôznych AI (alebo rôznych ľudí).
Testovateľnosť: Po napísaní kódu je možné okamžite automaticky overiť 90 % správnosti.
Udržiavateľnosť: O pol roka ktokoľvek, kto si prečíta špecifikáciu, pochopí pôvodný zámer.
Nízke komunikačné náklady: Tím diskutuje len o špecifikácii, nie o konkrétnych riadkoch kódu.
Bezpečnosť/kvalita vstavaná: Bezpečnostné požiadavky (napr. parametrické dotazy) a hraničné podmienky sú uvedené v špecifikácii, AI ich musí dodržať.

5. Príklad dobrej špecifikácie (minimalistická verzia)

# Spec: API na registráciu používateľa

## Rozsah
- Prijímať email, password
- Neodosielať overovací email, nekontrolovať reálnosť emailu

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

## Správanie
- email musí zodpovedať základnému formátu RFC 5322 (a@b.c)
- password: dĺžka 8–20, obsahovať aspoň jednu číslicu a jedno veľké písmeno
- Použiť bcrypt na šifrovanie, cost faktor 10
- Ak sa pred uložením do databázy zistí, že email už existuje → 409

## Testovacie prípady (vstup -> očakávaný stavový kód+polia odpovede)
| Vstup email | password | Očakávanie |
|------------|----------|------------|
| test@x.com | Pass1234  | 201, user_id existuje |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (existujúci email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Nefunkčné požiadavky
- SQL musí používať parametrické dotazy (ochrana proti injekcii)
- Logovať IP zdroja registrácie, neλογovať password
- Odozva 95 % požiadaviek < 100 ms (bez bcrypt)

## Závislosti
- Python 3.10+, FastAPI, bcrypt, asyncpg

Dobré Spec Coding = premena „rozhodnutí človeka“ na „testovacie prípady + typové signatúry + obmedzenia správania“ pre stroj, takže AI iba vypĺňa implementáciu, zatiaľ čo človek vždy kontroluje kvalitu a smer.