Intervista 16 tas-Serje AI: Kif għandu jkun spec coding tajjeb?

Spec Coding tajjeb (i.e., kodifikazzjoni mmexxija mill-istandards) għandu l-għan ewlieni li jbiddel "ideat imċajpra" f'"kuntratti preċiżi, verifikabbli u eżegwibbli". Mhuwiex biss kitba ta' dokument, imma l-istabbiliment ta' lingwaġġ ta' komunikazzjoni mingħajr ambigwità bejn il-bniedem u l-AI (jew bejn il-bnedmin). Hawn taħt, se nagħti stampa ta' kif għandu jkun spec tajjeb minn erba' dimensjonijiet: l-istruttura tal-kontenut tal-ispec, prinċipji tal-kitba, proċess ta' kollaborazzjoni mal-AI, u verifika tal-kwalità.

1. Struttura standard ta' dokument ta' spec (b'modulu ta' funzjonalità bħala eżempju)

Taqsima	Kontenut obbligatorju	Eżempju
1. Għan u Ambitu	Spjega f'sentenza waħda x'qed isir, speċifika x'mhux qed isir	"Implimenta API ta' reġistrazzjoni ta' utent, mhix inkluża verifika tal-email"
2. Kuntratt ta' Input/Output	Struttura tad-data, tip, kampijiet obbligatorji/opzjonali, eżempji ta' valuri	`POST /register` body `{email: string, password: string}`, risposta `201` jew `400` b'kodiċi ta' żball
3. Imġiba u Loġika	Regoli tan-negozju, kundizzjonijiet tal-limiti, transizzjonijiet ta' stat	"It-tul tal-password għandu jkun bejn 8-20 karattru, għandu jinkludi mill-inqas numru wieħed; jekk l-email diġà jeżisti, irritorna `409`"
4. Immaniġġjar ta' Żbalji	Xenarji ta' eċċezzjoni possibbli kollha u l-kodiċijiet/messaġġi ta' żball korrispondenti	"Konnessjoni tal-bażi tad-data falliet → irritorna `503`, ma tesponix il-stack"
5. Rekwiżiti Mhux Funzjonali	Prestazzjoni (ħin ta' rispons < 200ms), sigurtà (mistoqsija parametrizzata), logijiet, osservabilità	"Is-SQL kollha għandhom jużaw prekompilazzjoni; irreġistra `email` imma mhux `password`"
6. Każijiet ta' Test (kruċjali)	Mill-inqas 3 inputs tipiċi + 2 inputs tal-limiti/eċċezzjoni, b'output mistenni	Ara t-tabella t'hawn taħt
7. Dipendenzi u Restrizzjonijiet	Liema libreriji, verżjonijiet, varjabbli tal-ambjent jintużaw	"Python 3.10+, FastAPI, varjabbli tal-ambjent `DB_URL`"

Eżempju ta' Każijiet ta' Test (inkorporati fl-ispec)

Xenarju	Input	Output mistenni
Reġistrazzjoni normali	email: `a@b.com`, pwd: `Pass1234`	`201`, irritorna `user_id`
Password qasir wisq	pwd: `Ab1`	`400`, kodiċi ta' żball `WEAK_PASSWORD`
Email diġà jeżisti	l-istess email bħal hawn fuq	`409`, kodiċi ta' żball `EMAIL_EXISTS`

Spec tajjeb l-ewwel irid jikteb il-każijiet tat-test, għax l-AI tista' tiġġenera testijiet unitarji direttament minnhom, u tivverifika awtomatikament wara.

2. Prinċipji ewlenin tal-kitba ta' Spec (varjant ta' SMART)

Prinċipju	Spjegazzjoni	Eżempju ħażin
Preċiż (Precise)	Uża numri speċifiċi, tipi, kundizzjonijiet booleani; evita "kemm jista' jkun", "normalment"	❌ "Il-password għandha tkun sikura biżżejjed" → ✅ "Il-password għandu jkollha mill-inqas 8 karattri, b'ittra kbira, żgħira u numru"
Verifikabbli (Verifiable)	Kull rekwiżit jista' jiġi ġġudikat bħala mgħoddi/faliment permezz ta' test awtomatiku jew verifika manwali	❌ "Il-kodiċi għandu jkun eleganti" → ✅ "Il-kumplessità ċiklomatika tal-funzjoni ≤ 10, l-ebda blokk ta' kodiċi ripetut"
Mingħajr Ambigwità (Unambiguous)	L-istess terminu għandu tifsira konsistenti matul it-test kollu; agħti glossarju jekk meħtieġ	❌ "Jekk l-utent ma jeżistix, irritorna żball" → ✅ "Utent ma jeżistix → irritorna `404` u `{code: 'USER_NOT_FOUND'}`"
Komplut (Complete)	Jkopri l-mogħdija ferrieħa, il-mogħdijiet kollha ta' eċċezzjoni, u rekwiżiti mhux funzjonali	❌ Miktub biss xenarju ta' suċċess → ✅ Jinkludi timeout tal-bażi tad-data, nuqqas ta' permessi, eċċ.
Atomiku (Atomic)	Spec wieħed jiddeskrivi biss punt funzjonali wieħed li jista' jiġi kkunsinnat b'mod indipendenti (biex l-AI tkun tista' tlesti f'daqqa)	❌ Spec wieħed għal "is-sistema tal-ħlas kollha" → ✅ Maqsum f'"Ġenerazzjoni tal-ħlas", "Verifika tal-firma", "Rifużjoni"

3. Proċess ta' Spec Coding meta tikkollabora mal-AI

Il-bniedem jikteb l-ispec (l-istruttura ta' hawn fuq, speċjalment il-każijiet tat-test u s-sinjatura tal-funzjoni).
Agħti l-ispec kollu f'daqqa lill-AI (mhux b'żidiet ta' rekwiżiti b'konversazzjoni, biex tevita kontaminazzjoni tal-vibe).
L-AI tipproduċi l-kodiċi u t-testijiet unitarji (l-AI trid tiġġenera testijiet eżegwibbli skont il-każijiet tat-test fl-ispec).
Mexxi t-testijiet: jekk kollha jgħaddu, mur għall-pass li jmiss; jekk le, immodifika l-ispec jew ikkoreġi l-kodiċi direttament (f'dan il-punt jista' jidħol ċiklu żgħir, imma rreġistra l-bidliet).
Reviżjoni umana: iċċekkja jekk ġiex introdott funzjonalità barra l-ispec (scope creep), iċċekkja s-sigurtà/prestazzjoni.
Iffissar: issottometti d-dokument tal-ispec flimkien mal-kodiċi finali fir-repożitorju bħala dokument permanenti.

Prattika ewlenija: Kodifikazzjoni tal-ispec — uża spec.md + test_spec.py, fejn il-fajl tat-test jiġi direttament mill-eżempji fl-ispec, b'tali mod li meta timmodifika l-kodiċi aktar tard, tista' sempliċement tmexxi t-testijiet biex tivverifika jekk l-ispec ġiex miksur.

4. Effetti ta' Spec Tajjeb (jistgħu jintużaw bħala kriterji ta' aċċettazzjoni)

Determinazzjoni: L-istess spec mogħti lil AI differenti (jew persuni differenti) jipproduċi implimentazzjonijiet simili.
Testabbiltà: Wara li tinkiteb il-kodiċi, tista' immedjatament tivverifika awtomatikament 90% tal-korrettezza.
Manutenzjoni: Sitt xhur wara, kull min iħares lejn l-ispec jista' jifhem l-intenzjoni tad-disinn oriġinali.
Spejjeż baxxi ta' komunikazzjoni: Matul diskussjonijiet tat-tim, iddiskuti biss l-ispec, mhux il-linji tal-kodiċi speċifiċi.
Sigurtà/Kwalità inkorporata: Rekwiżiti ta' sigurtà (bħal mistoqsija parametrizzata) u kundizzjonijiet tal-limiti miktuba fl-ispec, l-AI trid tirrispettahom.

5. Eżempju ta' Spec Tajjeb (verżjoni sempliċi)

# Spec: API ta' Reġistrazzjoni ta' Utent

## Ambitu
- Jirċievi email, password
- Ma jibgħatx email ta' verifika, ma jiċċekkjax l-awtentiċità tal-email

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

## Imġiba
- email irid ikun konformi mal-format bażiku RFC 5322 (a@b.c)
- password: tul 8-20, għandu jinkludi mill-inqas numru wieħed u ittra kapitali waħda
- Uża bcrypt għall-ħażna kriptata, spiża tal-melħ 10
- Jekk jinstab li l-email diġà jeżisti qabel ma jiġi maħżun fil-bażi tad-data → 409

## Każijiet ta' Test (input -> kodiċi ta' stat mistenni + kamp ta' rispons)
| Input email | password | Mistenni |
|-------------|----------|----------|
| test@x.com | Pass1234  | 201, user_id jeżisti |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (email diġà jeżisti) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Mhux Funzjonali
- Is-SQL kollha għandhom jużaw mistoqsijiet parametrizzati (kontra l-injezzjoni)
- Il-log għandu jirreġistra l-IP tas-sors tar-reġistrazzjoni, ma jirreġistrax il-password
- Ħin ta' rispons 95% tal-petizzjonijiet < 100ms (eskluż bcrypt)

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

Spec Coding tajjeb = tbiddel "id-deċiżjonijiet tad-disinn" tal-bniedem f'"każijiet ta' test + firem tat-tipi + restrizzjonijiet tal-imġiba" tal-magna, biex l-AI timla biss l-implimentazzjoni, filwaqt li l-bniedem jibqa' jikkontrolla l-kwalità u d-direzzjoni.