AI serijos interviu 16: Kaip turėtų atrodyti geras spec kodavimas?

Geras Spec Coding (specifikacijomis varomas programavimas) esmė yra paversti „neaiškias idėjas“ į „tikslias, patikrinamas, vykdomas sutartis“. Tai ne tik dokumento rašymas, bet ir vienareikšmės bendravimo kalbos sukūrimas tarp žmonių ir AI (arba tarp žmonių). Toliau pateiksiu, kaip atrodo geras spec, iš turinio struktūros, rašymo principų, bendradarbiavimo su AI proceso ir kokybės patikrinimo.

1. Standartinė specifikacijos dokumento struktūra (funkcinio modulio pavyzdžiu)

Skyrius	Privalomas turinys	Pavyzdys
1. Tikslas ir apimtis	Vienu sakiniu apibūdinti, kas daroma, aiškiai nurodyti, kas nedaroma	„Įgyvendinti vartotojo registracijos API, neįtraukiant el. pašto patvirtinimo“
2. Įvesties/išvesties sutartis	Duomenų struktūra, tipai, privalomi/neprivalomi laukai, pavyzdinės reikšmės	`POST /register` užklausos kūnas `{email: string, password: string}`, atsakas `201` arba `400` su klaidos kodu
3. Veiksmai ir logika	Verslo taisyklės, ribinės sąlygos, būsenos perėjimai	„Slaptažodžio ilgis 8-20 simbolių, turi turėti bent vieną skaitmenį; jei el. paštas jau egzistuoja, grąžinti `409`“
4. Klaidų valdymas	Visi galimi išimtinių situacijų scenarijai ir atitinkami klaidų kodai / pranešimai	„Nepavyko prisijungti prie duomenų bazės → grąžinti `503`, neatskleidžiant klaidos krūvos“
5. Nefunkciniai reikalavimai	Našumas (atsako laikas < 200ms), saugumas (parametrizuotos užklausos), žurnalai, stebimumas	„Visos SQL užklausos turi būti iš anksto sukompiliuotos; registruoti `email`, bet neregistruoti `password`“
6. Testų atvejai (svarbu)	Ne mažiau 3 tipiniai įvesties + 2 ribiniai/išimtiniai, nurodyti tikėtiną išvestį	Žr. lentelę žemiau
7. Priklausomybės ir apribojimai	Kokios bibliotekos, versijos, aplinkos kintamieji	„Python 3.10+, FastAPI, aplinkos kintamasis `DB_URL`“

Testų atvejų pavyzdžiai (įdėti į spec)

Scenarijus	Įvestis	Tikėtina išvestis
Įprasta registracija	email: `a@b.com`, pwd: `Pass1234`	`201`, grąžina `user_id`
Per trumpas slaptažodis	pwd: `Ab1`	`400`, klaidos kodas `WEAK_PASSWORD`
El. paštas jau egzistuoja	tas pats email	`409`, klaidos kodas `EMAIL_EXISTS`

Geras spec pirmiausia turi turėti testų atvejus, nes AI pagal juos gali tiesiogiai sugeneruoti vienetų testus, o užbaigus automatiškai jais patikrinti.

2. Pagrindiniai spec rašymo principai (SMART variantas)

Principas	Paaiškinimas	Blogas pavyzdys
Tikslus (Precise)	Naudoti konkrečius skaičius, tipus, Bulio sąlygas, vengti „kiek įmanoma“, „paprastai“	❌ „Slaptažodis turi būti pakankamai saugus“ → ✅ „Slaptažodis bent 8 simboliai, turi didžiąją, mažąją raidę ir skaitmenį“
Patikrinamas (Verifiable)	Kiekvienas reikalavimas turi būti įvertinamas arba automatiniais testais, arba rankiniu patikrinimu kaip išlaikytas/neišlaikytas	❌ „Kodas turi būti elegantiškas“ → ✅ „Funkcijos ciklomatinis sudėtingumas ≤ 10, nėra pasikartojančių kodo blokų“
Vienareikšmis (Unambiguous)	Tos pačios sąvokos visame tekste turi tą pačią reikšmę, prireikus pateikti žodynėlį	❌ „Jei vartotojo nėra, grąžinti klaidą“ → ✅ „Vartotojo nėra → grąžinti `404` ir `{code: 'USER_NOT_FOUND'}`“
Išsamus (Complete)	Apimti laimingą kelią, visas išimtis, nefunkcinius reikalavimus	❌ Parašytas tik sėkmės scenarijus → ✅ Įtraukti duomenų bazės laiko limitą, nepakankamas teises ir kt.
Atominis (Atomic)	Vienas spec aprašo tik vieną savarankiškai pristatomą funkciją (kad AI galėtų atlikti iš karto)	❌ Vienas spec visai „mokėjimo sistemai“ → ✅ Išskaidyti į „mokėjimo orderio sukūrimą“, „grįžtamojo ryšio parašo patikrą“, „grąžinimą“

3. Spec kodavimo procesas bendradarbiaujant su AI

Žmogus rašo spec (minėta struktūra, ypač testų atvejus ir funkcijų parašus).
Spec pateikiamas AI vienu kartu (o ne dialogu pridedant reikalavimus, kad būtų išvengta „vibe“ užteršimo).
AI išveda kodą + vienetų testus (AI privalo pagal spec testų atvejus sugeneruoti vykdomus testus).
Paleisti testus: jei visi praeina, pereiti prie kito žingsnio; jei ne, pataisyti spec arba tiesiogiai kodą (tuomet galima maža iteracija, bet fiksuoti pakeitimus).
Žmogaus peržiūra: patikrinti, ar nėra papildomų funkcijų, neįtrauktų į spec (scope creep), patikrinti saugumą/našumą.
Įtvirtinimas: spec dokumentas ir galutinis kodas įtraukiami į versijų kontrolės sistemą kaip nuolatinė dokumentacija.

Pagrindinė praktika: Spec kodavimas – naudoti spec.md + test_spec.py, kur testų failas tiesiogiai atitinka spec pavyzdžius, kad vėliau keičiant kodą užtektų paleisti testus ir patikrinti, ar spec nepažeistas.

4. Gero spec poveikis (gali būti priėmimo kriterijai)

Determinuotumas: Tas pats spec skirtingiems AI (ar skirtingiems žmonėms) duoda panašų įgyvendinimą.
Testuojamumas: Parašius kodą iškart galima automatiškai patikrinti 90% teisingumo.
Priežiūra: Po pusmečio bet kas, pažiūrėjęs spec, supras pradinius dizaino sprendimus.
Mažos komunikacijos sąnaudos: Komandos diskutuoja tik apie spec, o ne apie konkrečias kodo eilutes.
Saugumas/kokybė iš anksto: Saugumo reikalavimai (pvz., parametrizuotos užklausos) ir ribinės sąlygos nurodyti spec, AI privalo jų laikytis.

5. Gero spec pavyzdys (supaprastintas)

# Spec: Vartotojo registracijos API

## Apimtis
- Priima email, password
- Nesiunčia patvirtinimo laiško, netikrina el. pašto tikrumo

## Sutartis
POST /register
Content-Type: application/json
Užklausa: { "email": string, "password": string }
Atsakas 201: { "user_id": string }
Atsakas 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Atsakas 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Veiksmai
- email turi atitikti RFC 5322 pagrindinį formatą (a@b.c)
- password: ilgis 8-20, turi turėti bent vieną skaitmenį ir vieną didžiąją raidę
- Naudoti bcrypt šifravimą saugojimui, druskos kaina 10
- Jei prieš įrašant į duomenų bazę nustatoma, kad email jau egzistuoja → 409

## Testų atvejai (įvestis -> tikėtinas statuso kodas+atsako laukas)
| Įvesties email | password | Tikėtina |
|----------------|----------|----------|
| test@x.com | Pass1234  | 201, user_id egzistuoja |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (jau egzistuojantis email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Nefunkciniai reikalavimai
- SQL užklausos turi būti parametrizuotos (apsauga nuo įterpimų)
- Žurnaluose fiksuoti registracijos šaltinio IP, neregistruoti slaptažodžio
- Atsako laikas 95% užklausų < 100ms (be bcrypt)

## Priklausomybės
- Python 3.10+, FastAPI, bcrypt, asyncpg

Geras Spec Coding = žmogaus „dizaino sprendimų“ pavertimas į mašinos „testų atvejus + tipo parašus + elgesio apribojimus“, leidžiantis AI užpildyti įgyvendinimą, o žmogui visada kontroliuoti kokybę ir kryptį.