Tambayar Aiki na AI 16: Menene ya kamata a yi spec coding mai kyau?

Kyakkyawan Spec Coding (tsarin shirye-shiryen da aka kora da ka'idoji), ainihin manufarsa ita ce canza 'tunanin da ba shi da tabbas' zuwa 'alkawari mai inganci, mai iya tabbatarwa, kuma mai aiwatarwa'. Ba kawai rubuta takarda ba ne, amma kafa harshen sadarwa maras shakku tsakanin mutum da AI (ko mutum da mutum).

A ƙasa, zan bayyana yadda kyakkyawan spec ya kamata ya kasance daga bangarori huɗu: tsarin abubuwan da ke cikin ka'idoji, ƙa'idodin rubutu, tsarin haɗin gwiwa da AI, da tabbatar da inganci.

ɗaya: Tsarin daidaitaccen takardar ka'idoji (misalin ƙungiyar aiki)

Babi	Abubuwan da ake buƙata	Misali
1. Manufa da iyaka	Bayani a cikin jimla ɗaya game da abin da za a yi, a bayyana abin da ba za a yi ba	"Aiwe da API na rajistar masu amfani, ba tare da tabbatar da imel ba"
2. Alkawarin shigarwa/fitarwa	Tsarin bayanai, nau'i, filayen dole/zaɓi, misali	`POST /register` Jikin buƙatun `{email: string, password: string}`, amsa `201` ko `400` tare da lambar kuskure
3. Hali da dabaru	Dokokin kasuwanci, yanayin iyaka, canjin yanayi	"Tsawon kalmar sirri 8-20, ya ƙunshi aƙalla lamba ɗaya; idan imel ya riga ya kasance, dawo da `409`"
4. Gudanar da kurakurai	Duk yanayin da ba daidai ba da kuma lambobin kuskure/saƙonnin da suka dace	"Rashin haɗin bayanai → dawo da `503`, kada a fallasa tari"
5. Bukatun marasa aiki	Yin aiki (lokacin amsawa < 200ms), tsaro (binciken sigogi), tarihin aiki, iya gani	"Duk SQL dole ne a yi amfani da shirye-shirye; rubuta `email` amma kada a rubuta `password`"
6. Misalan gwaji (mahimmanci)	Aƙalla shigarwar misali 3 + shigarwar iyaka/ban da 2, bayar da fitar da ake sa ran	Dubi teburin da ke ƙasa
7. Dogaro da ƙuntatawa	Amfani da wane ɗakin karatu, sigar, masu canjin yanayi	"Python 3.10+, FastAPI, mai canjin yanayi `DB_URL`"

Misalan gwaji (a cikin spec)

Yanayi	Shigarwa	Fitar da ake sa ran
Rajista na yau da kullun	email: `a@b.com`, pwd: `Pass1234`	`201`, dawo da `user_id`
Kalmar sirri ta gajarta	pwd: `Ab1`	`400`, lambar kuskure `WEAK_PASSWORD`
Imel ya riga ya kasance	imel iri ɗaya	`409`, lambar kuskure `EMAIL_EXISTS`

Kyakkyawan Spec dole ne ya fara rubuta misalan gwaji, saboda AI na iya samar da gwajin raka'a kai tsaye daga gare su, kuma idan an gama, za a iya tabbatarwa ta atomatik.

Biyu: Ƙa'idodin rubuta Spec (bambancin SMART)

Ƙa'ida	Bayani	Misali mara kyau
Madaidaici (Precise)	Yi amfani da takamaiman lambobi, nau'oi, yanayin gaskiya/ƙarya, kauce wa 'gwargwadon yiwuwa', 'yawanci'	❌ "Kalmar sirri ta kasance mai aminci sosai" → ✅ "Kalmar sirri aƙalla haruffa 8, ta ƙunshi babba, ƙarami, lambobi"
Mai iya tabbatarwa (Verifiable)	Kowane buƙatu za a iya tantance nasara/ gazawa ta hanyar gwaji ta atomatik ko bincike na hannu	❌ "Lambar ta kasance mai kyau" → ✅ "Hadadden madauki na ayyuka ≤ 10, babu tubalan lamba masu maimaita"
Mara shakku (Unambiguous)	Ma'anar kalma ɗaya a duk rubutun ta kasance iri ɗaya, idan ya cancanta a ba da ƙamus	❌ "Idan mai amfani ba ya wanzu, dawo da kuskure" → ✅ "Mai amfani ba ya wanzu → dawo da `404` da `{code: 'USER_NOT_FOUND'}`"
Cikakke (Complete)	Ya rufe hanyar farin ciki, duk hanyoyin ban da, da bukatun marasa aiki	❌ An rubuta yanayin nasara kawai → ✅ Ya haɗa da lokacin ƙare bayanai, rashin izini, da sauransu
Atomi (Atomic)	Spec ɗaya kawai ya bayyana aikin da za a iya isar da shi kai tsaye (domin sauƙaƙa AI ta kammala sau ɗaya)	❌ Yin amfani da spec ɗaya don rubuta 'dukan tsarin biyan kuɗi' → ✅ A raba zuwa 'ƙirƙirar takardar biyan kuɗi', 'sauki tabbatarwa', 'mayar da kuɗi'

Uku: Tsarin Spec Coding lokacin haɗin gwiwa da AI

Mutum ya rubuta spec (tsarin da ke sama, musamman rubuta misalan gwaji da sa hannun ayyuka).
A ciyar da AI spec ɗin a lokaci ɗaya (kada a ƙara buƙatu ta hanyar tattaunawa, don kauce wa gurɓatar vibe).
AI ya fitar da lamba + gwajin raka'a (AI dole ne ya samar da gwaje-gwajen da za a iya aiwatarwa bisa ga misalan gwaji a cikin spec).
Gudanar da gwaji: Idan duk sun wuce, shiga mataki na gaba; idan ba su wuce ba, gyara spec ko gyara lamba kai tsaye (a wannan lokacin za a iya shiga zagaye kaɗan, amma dole a rubuta canje-canje).
Bincike na hannu: Duba ko an shigar da ayyuka da suka wuce spec (scope creep), duba tsaro/ yin aiki.
Kafaffen: A gabatar da takardar spec da lambar ƙarshe tare zuwa ma'ajiyar, a matsayin takarda ta dindindin.

Muhimmin aiki: Ƙirƙirar lambar Spec — yi amfani da spec.md + test_spec.py, inda fayil ɗin gwaji ya fito kai tsaye daga misalan spec, don haka lokacin da ake gyara lamba daga baya, kawai gudanar da gwaji don tabbatar da ko spec ɗin ya lalace.

Hudu: Tasirin kyakkyawan Spec (za a iya amfani da shi azaman ma'aunin karɓa)

Tabbacin: Spec ɗaya idan aka ba wa AI daban-daban (ko mutane daban-daban) suna samar da aiwatarwa iri ɗaya.
Iya gwadawa: Bayan rubuta lamba, za a iya tabbatar da daidaito 90% ta atomatik nan take.
Iya kula da shi: Bayan rabin shekara, duk wanda ya kalli spec zai iya fahimtar manufar ƙira ta asali.
Ƙananan farashin sadarwa: Lokacin tattaunawa ta ƙungiya, kawai a tattauna spec, ba a tattauna takamaiman layukan lamba ba.
Tsaro/inganci a ciki: Bukatun tsaro (kamar binciken sigogi) da yanayin iyaka an rubuta su a cikin spec, AI dole ne ya bi su.

Biyar: Misalin kyakkyawan Spec (siga mafi sauki)

# Spec: API na rajistar masu amfani

## Iyaka
- Karɓi email, password
- Ba a aika saƙon tabbatarwa ba, ba a bincika gaskiyar imel ba

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

## Hali
- Dole ne email ya bi tsarin RFC 5322 na asali (a@b.c)
- password: tsawon haruffa 8-20, ya ƙunshi aƙalla lamba ɗaya da babban harafi ɗaya
- Yi amfani da bcrypt don ɓoye ajiya, farashin gishiri 10
- Idan an gano email ya riga ya kasance kafin a adana shi a cikin bayanai → 409

## Misalan gwaji (shigarwa -> lambar matsayin da ake sa ran + filin amsa)
| Shigar email | password | Abin da ake sa ran |
|--------------|----------|-------------------|
| test@x.com | Pass1234  | 201, user_id ya wanzu |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (imel da ya riga ya wanzu) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Marasa aiki
- Dole ne a yi amfani da binciken sigogi na SQL (hana injection)
- Tarihin aiki ya rubuta IP tushen rajista, kada ya rubuta password
- Lokacin amsawa 95% na buƙatu < 100ms (ba tare da bcrypt ba)

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

Kyakkyawan Spec Coding = Rubuta 'yanke shawara na mutum' a matsayin 'misalan gwaji + sa hannun nau'i + ƙuntatawar hali' na na'ura, don AI ya kula da cika aiwatarwa kawai, yayin da mutum koyaushe ke sarrafa inganci da jagora.