AI serieko elkarrizketa 16: Zein da spec coding on baten itxura?

Spec Coding on bat (espedifikazio bidezko programazioa) du helburu ideia lausoak kontratu zehatz, egiaztagarri eta exekutagarri bihurtzea. Ez da dokumentu bat idaztea bakarrik, baizik eta gizakiaren eta AI (edo gizakiaren eta gizakiaren) arteko komunikazio hizkuntza anbiguotasunik gabea ezartzea. Jarraian, espedifikazioaren eduki-egitura, idazketa-printzipioak, AI-rekin lankidetzan aritzeko prozesua eta kalitate-egiaztapena lau dimentsioetatik azalduko dut, spec on baten itxura emanez.

1. Espedifikazio-dokumentuaren egitura estandarra (funtzio-modulu baten adibidea)

Atala	Nahitaezko edukia	Adibidea
1. Helburua eta esparrua	Esaldi batean zer egin deskribatu, argi utzi zer ez den egingo	“Erabiltzaile erregistro APIa inplementatu, posta elektronikoko egiaztapenik gabe”
2. Sarrera/irteera kontratua	Datu-egitura, mota, derrigorrezko/aukerazko eremuak, adibide-balioak	`POST /register` eskaera gorputza `{email: string, password: string}`, erantzuna `201` edo `400` errore-kodearekin
3. Portaera eta logika	Negozio-arauak, muga-baldintzak, egoera-aldaketak	“Pasahitzak 8-20 karaktere, gutxienez zenbaki bat; posta elektronikoa badago, `409` itzuli”
4. Errore-kudeaketa	Salbuespen-egoera posible guztiak eta dagozkien errore-kode/mezuak	“Datu-basearen konexioak huts → `503` itzuli, ez piloa agerian utzi”
5. Funtzionalak ez diren eskakizunak	Errendimendua (erantzun-denbora < 200ms), segurtasuna (parametrizatutako kontsultak), erregistroak, behagarritasuna	“SQL guztiak aurrez konpilatu behar dira; `email` erregistratu baina `password` ez”
6. Proba kasuak (gakoa)	Gutxienez 3 sarrera tipiko + 2 muga/salbuespen sarrera, espero den irteera emanez	Ikusi beheko taula
7. Menpekotasunak eta murrizketak	Zein liburutegi, bertsio, ingurune-aldagai erabiltzen diren	“Python 3.10+, FastAPI, `DB_URL` ingurune-aldagaia”

Proba kasuen adibidea (spec-ean barneratua)

Eszenatokia	Sarrera	Espero den irteera
Erregistro normala	email: `a@b.com`, pwd: `Pass1234`	`201`, `user_id` itzuli
Pasahitz laburregia	pwd: `Ab1`	`400`, `WEAK_PASSWORD` errore-kodea
Posta elektronikoa existitzen da	Aurreko email bera	`409`, `EMAIL_EXISTS` errore-kodea

Spec on batek proba kasuak lehenik idatzi behar ditu, AIak horien arabera unitate-probak sor ditzakeelako, eta bukatutakoan automatikoki egiaztatu.

2. Spec idazteko oinarrizko printzipioak (SMART aldaera)

Printzipioa	Azalpena	Kontraadibidea
Zehaztasuna (Precise)	Zenbaki zehatzak, motak, baldintza boolearrak erabili, saihestu “ahalik eta”, “ohiko”	❌ “Pasahitza nahikoa segurua izan behar da” → ✅ “Pasahitzak gutxienez 8 karaktere, maiuskula, minuskula eta zenbaki bat izan behar ditu”
Egiaztagarritasuna (Verifiable)	Baldintza bakoitza proba automatikoen edo eskuzko egiaztapenaren bidez gainditu/huts egin dezakeela	❌ “Kodea dotorea izan behar da” → ✅ “Funtzioaren ziklo-konplexitatea ≤ 10, kode-bloke errepikaturik ez”
Anbiguotasunik eza (Unambiguous)	Termino berak esanahi bera du testu osoan, behar izanez gero glosarioa eman	❌ “Erabiltzailea existitzen ez bada, errorea itzuli” → ✅ “Erabiltzailea existitzen ez bada → `404` itzuli eta `{code: 'USER_NOT_FOUND'}`”
Osotasuna (Complete)	Bide zoriontsua, salbuespen-bide guztiak eta funtzionalak ez diren eskakizunak estali	❌ Arrakasta-eszenatokia soilik idatzi → ✅ Datu-basearen denbora-muga, baimen nahikorik ez, etab. sartu
Atomizazioa (Atomic)	Spec batek funtzio-puntu independente bat deskribatu behar du (AIk behin betetzeko modukoa)	❌ Spec bakar batekin “ordainketa-sistema osoa” idatzi → ✅ “Ordainketa-agiria sortu”, “Dei-itzulketaren sinadura egiaztatu”, “Itzulketa” zatitu

3. AI-rekin lankidetzan aritzeko Spec Coding prozesua

Gizakiak spec idatzi (goiko egitura, bereziki proba kasuak eta funtzio sinadurak ondo idatzi).
Spec-a AI-ri behin eman (ez elkarrizketa bidez eskakizunak gehitu, vibe kutsadura saihesteko).
AI-k kodea + unitate probak atera (AI-k spec-eko proba kasuen arabera proba exekutagarriak sortu behar ditu).
Probak exekutatu: denak gainditzen baditu, hurrengo urratsera; gainditzen ez baditu, spec-a aldatu edo zuzenean kodean zuzendu (orduan ziklo txiki batean sar daiteke, baina aldaketak erregistratu behar dira).
Gizakiaren berrikuspena: spec-etik kanpoko funtziorik sartu den (scope creep) egiaztatu, segurtasuna/errendimendua egiaztatu.
Sendotzea: spec dokumentua eta azken kodea biltegira bidali, dokumentu iraunkor gisa.

Praktika gakoa: Spec kode bihurtzea —— spec.md + test_spec.py erabili, non proba fitxategia spec-eko adibideetatik zuzenean datorren. Horrela, kodea aldatzean probak exekutatzea nahikoa da spec-a urratu den egiaztatzeko.

4. Spec on baten ondorioak (onarpen-irizpidetzat erabil daitezke)

Zehaztasuna: Spec bera emanda AI ezberdinei (edo pertsona ezberdinei) antzeko inplementazioak sortzen ditu.
Probagarritasuna: Kodea idatzi bezain pronto, automatikoki egiaztatu daiteke %90eko zuzentasuna.
Mantengarritasuna: Sei hilabete geroago, edonork spec-a ikusita, jatorrizko diseinu-asmoa uler dezake.
Komunikazio-kostu baxua: Taldeko eztabaidetan spec-a soilik eztabaidatu, kode-lerro zehatzak ez.
Segurtasuna/kalitatea barneratuta: Segurtasun-eskakizunak (parametrizatutako kontsultak) eta muga-baldintzak spec-ean idatzita, AIk bete behar ditu.

5. Spec on baten adibidea (bertsio minimoa)

# Spec: Erabiltzaile erregistro APIa

## Esparrua
- email, password jaso
- Ez bidali egiaztapen-mezurik, ez egiaztatu posta elektronikoaren benetakotasuna

## Kontratua
POST /register
Content-Type: application/json
Eskaera: { \"email\": string, \"password\": string }
Erantzuna 201: { \"user_id\": string }
Erantzuna 400: { \"code\": \"INVALID_PASSWORD\" | \"INVALID_EMAIL\" }
Erantzuna 409: { \"code\": \"EMAIL_ALREADY_EXISTS\" }

## Portaera
- email-ak RFC 5322 formatu oinarrizkoa bete behar du (a@b.c)
- pasahitza: 8-20 karaktere, gutxienez zenbaki bat eta maiuskula bat
- bcrypt erabiliz gorde, gatz kostua 10
- Datu-basean gorde baino lehen email-a existitzen bada → 409

## Proba kasuak (sarrera -> espero den egoera-kodea+erantzun eremua)
| Sarrera email | pasahitza | Espero dena |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id existitzen da |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (dagoeneko existitzen den email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Funtzionalak ez direnak
- SQL-ak parametrizatutako kontsultak erabili behar ditu (injekzioa saihesteko)
- Erregistroak jatorriko IP-a gorde, pasahitza ez
- Erantzun denbora %95 eskaera < 100ms (bcrypt gabe)

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

Spec Coding on bat = giza erabaki diseinuak makinen \"proba kasu + mota sinadura + portaera murrizketa\" bihurtzea, AIa inplementazioa betetzera mugatuz, eta gizakiak kalitatea eta norabidea beti kontrolatuz.