AI sērijas intervija 16: Kādam jābūt labam spec kodējumam?

Labs Spec Coding (specifikāciju vadīta programmēšana) pamatā ir pārvērst "neskaidras idejas" par "precīziem, pārbaudāmiem un izpildāmiem līgumiem". Tas nav tikai dokumenta rakstīšana, bet gan neviennozīmīgas saziņas valodas izveide starp cilvēku un AI (vai starp cilvēkiem). Turpmāk es parādīšu, kā izskatās labs spec, no četrām dimensijām: specifikācijas satura struktūra, rakstīšanas principi, sadarbības process ar AI, kvalitātes pārbaude.

1. Specifikācijas dokumenta standarta struktūra (ar funkcionālo moduli kā piemēru)

Sadaļa	Obligātais saturs	Piemērs
1. Mērķis un darbības joma	Vienā teikumā paskaidrot, ko dara, skaidri norādot, ko nedara	"Izveidot lietotāja reģistrācijas API, neiekļaujot e-pasta verifikāciju"
2. Ievades/izvades līgums	Datu struktūra, tips, obligātie/neobligātie lauki, piemēra vērtības	`POST /register` pieprasījuma pamatteksts `{email: string, password: string}`, atbilde `201` vai `400` ar kļūdas kodu
3. Uzvedība un loģika	Biznesa noteikumi, robežnosacījumi, stāvokļa maiņa	"Paroles garums 8-20 rakstzīmes, jāsatur vismaz viens cipars; ja e-pasts jau eksistē, atgriezt `409`"
4. Kļūdu apstrāde	Visi iespējamie izņēmuma scenāriji un atbilstošie kļūdu kodi/ziņojumi	"Datubāzes savienojuma kļūme → atgriezt `503`, neizpaust kaudzes izsekojumu"
5. Nefunkcionālās prasības	Veiktspēja (atbildes laiks < 200 ms), drošība (parametrizēti vaicājumi), žurnāli, novērojamība	"Visiem SQL jāizmanto priekškompilēti vaicājumi; ierakstīt `email`, bet neierakstīt `password`"
6. Testa gadījumi (svarīgi)	Vismaz 3 tipiski ievades dati + 2 robežas/izņēmuma dati, norādot paredzamo izvadi	Skatīt tabulu zemāk
7. Atkarības un ierobežojumi	Kādas bibliotēkas, versijas, vides mainīgie	"Python 3.10+, FastAPI, vides mainīgais `DB_URL`"

Testa gadījumu piemērs (iegults spec)

Scenārijs	Ievade	Paredzamā izvade
Normāla reģistrācija	email: `a@b.com`, pwd: `Pass1234`	`201`, atgriež `user_id`
Pārāk īsa parole	pwd: `Ab1`	`400`, kļūdas kods `WEAK_PASSWORD`
E-pasts jau eksistē	tas pats email	`409`, kļūdas kods `EMAIL_EXISTS`

Labs spec vispirms jāuzraksta testa gadījumi, jo AI var ģenerēt vienību testus tieši no tiem un pēc pabeigšanas automātiski pārbaudīt.

2. Spec rakstīšanas pamatprincipi (SMART variants)

Princips	Skaidrojums	Pretpiemērs
Precizitāte (Precise)	Izmantot konkrētus skaitļus, tipus, Būla nosacījumus; izvairīties no "cik vien iespējams", "parasti"	❌ "Parolei jābūt pietiekami drošai" → ✅ "Parole vismaz 8 rakstzīmes, satur lielo, mazo burtu un ciparu"
Pārbaudāmība (Verifiable)	Katru prasību var noteikt kā izturētu/nav izturētu, izmantojot automātiskos testus vai manuālu pārbaudi	❌ "Kodam jābūt elegantam" → ✅ "Funkcijas ciklomātiskā sarežģītība ≤ 10, bez dublētiem koda blokiem"
Neviennozīmīgums (Unambiguous)	Vienam terminam visā tekstā jābūt vienādai nozīmei; nepieciešamības gadījumā sniegt glosāriju	❌ "Ja lietotājs neeksistē, atgriezt kļūdu" → ✅ "Lietotājs neeksistē → atgriezt `404` un `{code: 'USER_NOT_FOUND'}`"
Pilnīgums (Complete)	Aptvert laimīgo ceļu, visus izņēmuma ceļus, nefunkcionālās prasības	❌ Tikai veiksmes scenārijs → ✅ Iekļaut datubāzes taimautu, nepietiekamas tiesības u.c.
Atomiskums (Atomic)	Viens spec apraksta tikai vienu neatkarīgi piegādājamu funkcionalitāti (lai AI varētu izpildīt vienā reizē)	❌ Vienā spec rakstīt "visu maksājumu sistēmu" → ✅ Sadalīt "maksājuma rīkojuma ģenerēšana", "atgriezeniskā zvana paraksta pārbaude", "atmaksa"

3. Spec kodēšanas process sadarbībā ar AI

Cilvēks raksta spec (iepriekš minētā struktūra, īpaši testa gadījumi un funkciju signatūras).
Vienā reizē ievada spec AI (nevis dialoga veidā papildina prasības, lai izvairītos no vibes piesārņojuma).
AI izvada kodu + vienību testus (AI jāģenerē izpildāmi testi atbilstoši spec testa gadījumiem).
Palaist testus: ja visi iztur, pāriet uz nākamo soli; ja neiztur, labot spec vai tieši kodu (šajā posmā var ieiet mazā cilpā, bet jāreģistrē izmaiņas).
Cilvēka pārskats: pārbaudīt, vai nav ieviesta funkcija ārpus spec (darbības jomas paplašināšana), pārbaudīt drošību/veiktspēju.
Stabilizācija: spec dokumentu un galīgo kodu kopā iesniegt repozitorijā kā pastāvīgu dokumentāciju.

Praktisks ieteikums: Spec koda formātā — izmantot spec.md + test_spec.py, kur testa fails tieši nāk no spec piemēriem, tādējādi turpmāk modificējot kodu, vienkārši palaižot testus var pārbaudīt, vai spec nav salauzts.

4. Laba spec radītie efekti (var kalpot kā pieņemšanas kritēriji)

Determinisms: viens un tas pats spec, dots dažādiem AI (vai dažādiem cilvēkiem), rada līdzīgu implementāciju.
Testējamība: pēc koda uzrakstīšanas uzreiz var automātiski pārbaudīt 90% pareizības.
Uzturamība: pēc pusgada jebkurš, kas skatās spec, var saprast sākotnējo dizaina nodomu.
Zemas komunikācijas izmaksas: komanda diskutē tikai par spec, nevis par konkrētām koda rindām.
Iebūvēta drošība/kvalitāte: drošības prasības (piem., parametrizēti vaicājumi) un robežnosacījumi ir norādīti spec, AI tiem jāievēro.

5. Laba spec piemērs (minimālistisks)

# Spec: Lietotāja reģistrācijas API

## Darbības joma
- Saņemt email, password
- Nenosūtīt verifikācijas e-pastu, nepārbaudīt e-pasta īstumu

## Līgums
POST /register
Content-Type: application/json
Pieprasījums: { "email": string, "password": string }
Atbilde 201: { "user_id": string }
Atbilde 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Atbilde 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Uzvedība
- email jāatbilst RFC 5322 pamatformātam (a@b.c)
- password: garums 8-20, jāsatur vismaz viens cipars un viens lielais burts
- Izmantot bcrypt šifrēšanai, sāls koeficients 10
- Ja pirms saglabāšanas datubāzē konstatē, ka email jau eksistē → 409

## Testa gadījumi (ievade -> paredzamais statusa kods+atbildes lauks)
| Ievade email | password | Paredzamā izvade |
|--------------|----------|------------------|
| test@x.com   | Pass1234 | 201, user_id eksistē |
| test@x.com   | pass     | 400, INVALID_PASSWORD |
| bad          | Pass1234 | 400, INVALID_EMAIL |
| (jau eksistējošs email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Nefunkcionālās prasības
- SQL jāizmanto parametrizēti vaicājumi (pretinjektīvi)
- Žurnālos reģistrēt reģistrācijas avota IP, nereģistrēt paroli
- Atbildes laiks 95% pieprasījumu < 100 ms (bez bcrypt)

## Atkarības
- Python 3.10+, FastAPI, bcrypt, asyncpg

Labs Spec Coding = cilvēka "dizaina lēmumu" pārvēršana mašīnas "testa gadījumos + tipa signatūrās + uzvedības ierobežojumos", ļaujot AI tikai aizpildīt implementāciju, kamēr cilvēks vienmēr kontrolē kvalitāti un virzienu.