Ingqungquthela Yengxoxo Ye-AI 16: I-spec coding enhle kufanele ibe kanjani?

I-spec coding enhle (ukuhlela okwenziwa yi-spec), umongo wayo ukuguqula 'imibono engaqondakali' ibe 'isivumelwano esiqondile, esiqinisekiswayo, futhi esenziwayo'. Akusikho nje ukubhala idokhumenti, kodwa ukwakha ulimi lokuxhumana olungenakugxambukela phakathi komuntu ne-AI (noma umuntu nomuntu). Ngezansi ngizokunikeza isikhombisi se-spec enhle ngemikhakha emine: isakhiwo se-spec, izimiso zokubhala, inqubo yokusebenzisana ne-AI, nokuqinisekisa ikhwalithi.

1. Isakhiwo esijwayelekile sedokhumenti ye-spec (ngesibonelo semojula yomsebenzi)

Isahluko	Okuphoqelekile	Isibonelo
1. Inhloso nobubanzi	Ichaza ngomusho ukuthi kwenziwani, kucaciswe okungenziwa	"Senza i-API yokubhalisa umsebenzisi, akufaki ukuqinisekisa i-imeyili"
2. Isivumelwano sokufaka/okukhiphayo	Isakhiwo sedatha, uhlobo, amasimu aphoqelekile/okukhetha, amanani ayizibonelo	Umzimba wesicelo `{email: string, password: string}`, impendulo `201` noma `400` enekhodi yephutha
3. Ukuziphatha nengqikathi	Imithetho yebhizinisi, izimo zemikhawulo, ukushintsha kwesimo	Ubude bephasiwedi 8-20 amasign, okungenani inombolo eyodwa; uma i-imeyili isikhona buyisela `409`
4. Ukusingatha amaphutha	Zonke izimo ezingavamile ezingenzeka kanye nezikhodi/imilayezo yamaphutha	Ukuhluleka kokuxhuma database → buyisela `503`, ungabezi isitaki
5. Izidingo ezingezona ezenziwayo	Ukusebenza (isikhathi sokuphendula < 200ms), ukuphepha (imibuzo enemikhawulo), amalogi, ukubonakala	Wonke ama-SQL kufanele asebenzise ukuhlanganiswa kwangaphambili; qopha `email` kodwa ungaqophi `password`
6. Izimo zokuhlola (ezibalulekile)	Okungenani izimo ezi-3 ezijwayelekile + izimo ezi-2 zemikhawulo/ezindala, unikeze okulindelekile	Bona ithebula elingezansi
7. Izithembiso nezithiyo	Yimuphi umtapo, inguqulo, okuguquguqukayo kwendawo	Python 3.10+, FastAPI, okuguquguqukayo kwendawo `DB_URL`

Izimo zokuhlola isibonelo (ezifakiwe kuspec)

Isimo	Okufakiwe	Okulindelekile okukhiphayo
Ukubhalisa okujwayelekile	email: a@b.com, pwd: Pass1234	201, buyisela i-user_id
Iphasiwedi imfushane kakhulu	pwd: Ab1	400, ikhodi yephutha WEAK_PASSWORD
I-imeyili isivele ikhona	I-imeyili efanayo	409, ikhodi yephutha EMAIL_EXISTS

I-spec enhle kufanele ibhale izimo zokuhlola kuqala, ngoba i-AI ingakwazi ukukhiqiza izivivinyo zamayunithi ngokuqondile ngazo, bese iqinisekisa ngokuzenzakalelayo.

2. Izimiso eziyinhloko zokubhala i-Spec (inguqulelo ye-SMART)

Isimiso	Incazelo	Isibonelo esiphambene
Ukucacile (Precise)	Sebenzisa izinombolo eziqondile, izinhlobo, izimo ze-boolean, gwema 'ngangokunokwenzeka', 'imvamisa'	❌ 'Iphasiwedi kufanele iphephe ngokwanele' → ✅ 'Iphasiwedi okungenani ama-8, inamakapithali, amancane, izinombolo'
Okulungile (Verifiable)	Isidingo ngasinye kufanele sihloleke ngokuhlolwa okuzenzakalelayo noma ukuhlolwa komuntu ukuthi sidlulile noma sehlulekile	❌ 'Ikhodi kufanele ibe nokuhle' → ✅ 'Ukuxaka kwesekethe yomsebenzi ≤ 10, azikho izingxenye zekhodi eziphindayo'
Okungenakugxambukela (Unambiguous)	Igama elifanayo lichaza into efanayo kuyo yonke ingqungquthela, uma kunesidingo nikeza incazelo	❌ 'Uma umsebenzisi engekho, buyisela iphutha' → ✅ 'Umsebenzisi engekho → buyisela `404` kanye `{code: 'USER_NOT_FOUND'}`'
Okuphelele (Complete)	Kuhlanganisa indlela ejabulisayo, zonke izindlela ezingavamile, nezidingo ezingezona ezenziwayo	❌ Kubhalwe izimo eziphumelelayo kuphela → ✅ Kuhlanganisa ukuphelelwa isikhathi kwedatabase, ukungabi namvume, njll.
Okwezinto (Atomic)	I-spec eyodwa ichaza umsebenzi owodwa ozimele (ukuze i-AI ikwazi ukuwenza ngokugcwele)	❌ Sebenzisa i-spec eyodwa ukubhala 'uhlelo lonke lokukhokha' → ✅ Hlukanisa 'ukudala i-oda lokukhokha', 'ukuhlola isiginesha esakayo', 'ukubuyisela imali'

3. Inqubo ye-Spec Coding lapho usebenzisana ne-AI

Umuntu ubhala i-spec (isakhiwo esingenhla, ikakhulukazi abhale izimo zokuhlola nezisayina zemisebenzi).
Nikeza i-AI i-spec ngasikhathi sinye (ungafaki izidingo ngengxoxo, ukuze ugweme ukungcola kwe-vibe).
I-AI ikhiphe ikhodi + izivivinyo zamayunithi (I-AI kufanele ikhiqize izivivinyo ezenzakalelayo ngokusekelwe ezimweni zokuhlola ezisephecini).
Hlola izivivinyo: Uma zonke zidlulile, qhubeka; uma zingadluli, lungisa i-spec noma ikhodi ngokuqondile (kungase kube nesekethe encane, kodwa qopha izinguquko).
Ukubuyekeza komuntu: Hlola ukuthi akukho misebenzi engaphandle kwe-spec okungeniwe (scope creep), hlola ukuphepha/ukusebenza.
Hlanganisa: Thumela idokhumenti ye-spec nekhodi yokugcina endaweni yokugcina, njengombhalo ohlala njalo.

Umkhuba obalulekile: Ukuguqulwa kwe-spec kube yikhodi — sebenzisa spec.md + test_spec.py, lapho ifayela lokuhlola livela ngokuqondile ezibonelweni ezisephecini, ukuze uma ulungisa ikhodi ngemuva, usuke usebenza izivivinyo ukuqinisekisa ukuthi i-spec ayonakalanga.

4. Imiphumela ye-Spec enhle (ingasetshenziswa njengezindlela zokwamukela)

Ukucacisisa: I-spec efanayo inikwa ama-AI ahlukene (noma abantu abahlukene) ikhiqize ukusetshenziswa okufanayo.
Ukuhlolwa: Emva kokubhala ikhodi, ngukushesha kungaqinisekiswa ngokuzenzakalelayo ubuqiniso obungu-90%.
Ukwelashwa: Ngemuva kwengxenye yonyaka, noma ubani obheka i-spec angakwazi ukuqonda inhloso yedizayini yokuqala.
Izindleko eziphansi zokuxhumana: Lapho iqembu lixoxa, kuxoxwa nge-spec kuphela, hhayi imigqa yekhodi ethile.
Ukuphepha/ikhwalithi kufakiwe: Izidingo zokuphepha (njengemibuzo enemikhawulo) nezimo zemikhawulo zibhaliwe kuspec, i-AI kufanele izilandele.

5. Isibonelo se-Spec enhle (inguqulo elula kakhulu)

# Spec: I-API yokubhalisa umsebenzisi

## Ububanzi
- Thola i-imeyili, iphasiwedi
- Ayithumeli i-imeyili yokuqinisekisa, ayihloli ubuqiniso be-imeyili

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

## Ukuziphatha
- I-imeyili kufanele ihambisane nefomethi eyisisekelo ye-RFC 5322 (a@b.c)
- Iphasiwedi: ubude 8-20, okungenani inombolo eyodwa nohlamvu olukhulu olulodwa
- Sebenzisa i-bcrypt ukubhala ngendlela efihliwe, izindleko zikasawoti 10
- Uma ngaphambi kokugcina ku-database kutholakala ukuthi i-imeyili isivele ikhona → 409

## Izimo zokuhlola (okufakiwe -> ikhodi yesimo esilindelekile + inkambu yempendulo)
| Okufakiwe i-imeyili | iphasiwedi | Okulindelekile |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id ikhona |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| I-imeyili esivele ikhona | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Okungezona ezenziwayo
- Ama-SQL kufanele asebenzise imibuzo enemikhawulo (ukugwema ukufakwa okungenamlutha)
- Amalogi aqopha i-IP yomthombo wokubhalisa, angaqophi iphasiwedi
- Isikhathi sokuphendula 95% yezicelo < 100ms (ngaphandle kwe-bcrypt)

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

I-Spec Coding enhle = ukubhala 'izinqumo zedizayini' zomuntu zibe 'izimo zokuhlola + isiginesha yohlobo + imikhawulo yokuziphatha' kwemishini, vumela i-AI ukuthi igcwalise ukusetshenziswa, kuyilapho umuntu ehlala elawula ikhwalithi nesiqondiso.