AI série rozhovorů 16: Jak by mělo vypadat dobré spec kódování?

Dobré Spec kódování (specifikace řízené programování) spočívá v přeměně „mlhavých nápadů“ na „přesné, ověřitelné a vykonatelné kontrakty“. Nejde jen o psaní dokumentu, ale o vytvoření jednoznačného komunikačního jazyka mezi člověkem a AI (nebo mezi lidmi). Níže uvedu, jak vypadá dobrá specifikace z hlediska obsahové struktury specifikace, principů psaní, procesu spolupráce s AI a ověřování kvality.

一、Standardní struktura dokumentu specifikace (na příkladu funkčního modulu)

Kapitola	Povinný obsah	Příklad
1. Cíl a rozsah	Jednou větou popsat, co se dělá, a jasně uvést, co se nedělá	„Implementovat API pro registraci uživatele, nezahrnuje ověření e-mailu“
2. Vstupní/výstupní kontrakt	Datová struktura, typy, povinná/volitelná pole, příklady hodnot	`POST /register` tělo požadavku `{email: string, password: string}`, odpověď `201` nebo `400` s chybovým kódem
3. Chování a logika	Obchodní pravidla, okrajové podmínky, přechody stavů	„Délka hesla 8-20 znaků, alespoň jedno číslo; pokud e-mail již existuje, vraťte `409`“
4. Zpracování chyb	Všechny možné výjimky a odpovídající chybové kódy/zprávy	„Selhání připojení k databázi → vraťte `503`, nezveřejňujte stack trace“
5. Nefunkční požadavky	Výkon (doba odezvy < 200 ms), bezpečnost (parametrizované dotazy), logování, pozorovatelnost	„Všechny SQL dotazy musí používat předpřipravené příkazy; zaznamenávejte `email`, ale ne `password`“
6. Testovací případy (klíčové)	Alespoň 3 typické vstupy + 2 okrajové/výjimečné vstupy, uveďte očekávaný výstup	viz tabulka níže
7. Závislosti a omezení	Jaké knihovny, verze, proměnné prostředí	„Python 3.10+, FastAPI, proměnná prostředí `DB_URL`“

Testovací případy (vložené do specifikace)

Scénář	Vstup	Očekávaný výstup
Normální registrace	email: `a@b.com`, pwd: `Pass1234`	`201`, vrátí `user_id`
Heslo příliš krátké	pwd: `Ab1`	`400`, chybový kód `WEAK_PASSWORD`
E-mail již existuje	stejný email	`409`, chybový kód `EMAIL_EXISTS`

Dobrá specifikace musí nejprve napsat testovací případy, protože AI na jejich základě může přímo generovat unit testy a po dokončení automaticky ověřit.

二、Hlavní principy psaní specifikace (varianta SMART)

Princip	Vysvětlení	Protipříklad
Přesný (Precise)	Používejte konkrétní čísla, typy, booleovské podmínky, vyhněte se „pokud možno“, „obvykle“	❌ „Heslo musí být dostatečně bezpečné“ → ✅ „Heslo alespoň 8 znaků, obsahuje velké písmeno, malé písmeno, číslo“
Ověřitelný (Verifiable)	Každý požadavek musí být možné určit jako splněný/nesplněný automatickým testem nebo ruční kontrolou	❌ „Kód musí být elegantní“ → ✅ „Cyklická složitost funkce ≤ 10, žádné duplicitní bloky kódu“
Jednoznačný (Unambiguous)	Stejný termín má konzistentní význam v celém textu, v případě potřeby uveďte slovník	❌ „Pokud uživatel neexistuje, vraťte chybu“ → ✅ „Uživatel neexistuje → vraťte `404` a `{code: 'USER_NOT_FOUND'}`“
Úplný (Complete)	Pokrývá happy path, všechny výjimečné cesty, nefunkční požadavky	❌ Napsán pouze úspěšný scénář → ✅ Zahrnuje timeout databáze, nedostatečná oprávnění atd.
Atomický (Atomic)	Jedna specifikace popisuje pouze jeden nezávisle dodavatelný funkční bod (aby AI mohla dokončit najednou)	❌ Pomocí jedné specifikace napsat „celý platební systém“ → ✅ Rozdělit na „vytvoření platebního příkazu“, „ověření podpisu callbacku“, „vrácení peněz“

三、Proces Spec kódování při spolupráci s AI

Člověk napíše specifikaci (výše uvedená struktura, zejména testovací případy a signatury funkcí).
Specifikaci vložte AI najednou (nepřidávejte požadavky formou konverzace, abyste předešli „vibe pollution“).
AI vygeneruje kód + unit testy (AI musí podle testovacích případů ve specifikaci vytvořit spustitelné testy).
Spusťte testy: Pokud všechny projdou, pokračujte; pokud ne, upravte specifikaci nebo přímo opravte kód (v tomto okamžiku lze vstoupit do malého cyklu, ale změny je třeba zaznamenat).
Ruční kontrola: Zkontrolujte, zda nebyly zavedeny funkce mimo specifikaci (scope creep), zkontrolujte bezpečnost/výkon.
Uložte: Odešlete dokument specifikace a finální kód do úložiště jako trvalou dokumentaci.

Klíčová praxe: Specifikace jako kód — použijte spec.md + test_spec.py, kde testovací soubory přímo vycházejí z příkladů ve specifikaci, takže při pozdějších úpravách kódu stačí spustit testy k ověření, zda specifikace nebyla narušena.

四、Přínosy dobré specifikace (lze použít jako akceptační kritéria)

Determinismus: Stejná specifikace poskytnutá různým AI (nebo lidem) vede k podobným implementacím.
Testovatelnost: Po napsání kódu lze automaticky ověřit 90 % správnosti.
Udržovatelnost: Po půl roce kdokoli, kdo se podívá na specifikaci, pochopí původní záměr návrhu.
Nízké komunikační náklady: Během týmové diskuze se diskutuje pouze specifikace, ne konkrétní řádky kódu.
Bezpečnost/kvalita vestavěná: Bezpečnostní požadavky (např. parametrizované dotazy) a okrajové podmínky jsou uvedeny ve specifikaci, AI je musí dodržovat.

五、Příklad dobré specifikace (minimalistická verze)

# Spec: API pro registraci uživatele

## Rozsah
- Přijímá email, password
- Neodesílá ověřovací e-mail, nekontroluje pravost e-mailu

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

## Chování
- email musí odpovídat základnímu formátu RFC 5322 (a@b.c)
- password: délka 8-20, alespoň jedno číslo a jedno velké písmeno
- Použijte bcrypt pro šifrované uložení, salt cost 10
- Pokud je email nalezen již před uložením do databáze → 409

## Testovací případy (vstup -> očekávaný stavový kód + pole odpovědi)
| Vstupní email | password | Očekávání |
|---------------|----------|-----------|
| test@x.com    | Pass1234 | 201, user_id existuje |
| test@x.com    | pass     | 400, INVALID_PASSWORD |
| bad           | Pass1234 | 400, INVALID_EMAIL |
| (již existující e-mail) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Nefunkční požadavky
- SQL musí používat parametrizované dotazy (ochrana proti injekci)
- Logování zaznamenává IP zdroje registrace, nezaznamenává heslo
- Doba odezvy 95 % požadavků < 100 ms (bez bcrypt)

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

Dobré Spec kódování = napsat „rozhodnutí o návrhu“ člověka jako „testovací případy + typové signatury + omezení chování“ pro stroj, což AI nechá pouze vyplnit implementaci, zatímco člověk vždy řídí kvalitu a směr.