Mfululizo wa AI 16: Spec coding nzuri inapaswa kuwa vipi?

Spec Coding (usimbaji unaoendeshwa na vipimo) bora, msingi wake ni kubadilisha "wazo lisilo wazi" kuwa "mkataba sahihi, unaoweza kuthibitishwa, na unaotekelezeka". Si tu kuandika hati, bali ni kuanzisha lugha ya mawasiliano isiyo na utata kati ya binadamu na AI (au binadamu na binadamu). Hapa chini nitaelezea kwa nyanja nne: muundo wa maudhui ya vipimo, kanuni za uandishi, mchakato wa ushirikiano na AI, na uthibitishaji wa ubora, ili kutoa picha ya spec nzuri.

1. Muundo wa kawaida wa hati ya vipimo (kwa mfano wa moduli ya kazi)

Sehemu	Maudhui ya lazima	Mfano
1. Lengo na upeo	Eleza kwa sentensi moja nini kitafanyika, na wazi nini hakitafanyika	"Tekeza API ya usajili wa watumiaji, isijumuishe uthibitishaji wa barua pepe"
2. Mkataba wa ingizo/toweo	Muundo wa data, aina, sehemu za lazima/za hiari, thamani za mfano	`POST /register` kiombi `{email: string, password: string}`, jibu `201` au `400` likiwa na msimbo wa kosa
3. Tabia na mantiki	Kanuni za biashara, mipaka ya hali, mabadiliko ya hali	"Nenosiri lenye urefu wa herufi 8-20, angalau namba moja; barua pepe ikiwa tayari ipo rudisha `409`"
4. Ushughulikiaji wa makosa	Matukio yote yanayowezekana ya hitilafu na misimbo/jumbe za makosa	"Muunganisho wa hifadhidata umeshindwa → rudisha `503`, usifichue mrundikano wa wito"
5. Mahitaji yasiyofanya kazi	Utendaji (muda wa kujibu < 200ms), usalama (maswali yaliyojibiwa kwa vigezo), kumbukumbu, uwezo wa kuchunguza	"SQL zote lazima zitumie utayarishaji iliyotangulia; rekodi `email` lakini usirekodi `password`"
6. Kesi za majaribio (muhimu)	Angalau pembejeo 3 za kawaida + 2 za mpaka/hitilafu, toa matokeo yanayotarajiwa	Tazama jedwali hapa chini
7. Vitegemezi na vikwazo	Tumia maktaba gani, matoleo, vigezo vya mazingira	"Python 3.10+, FastAPI, kigezo cha mazingira `DB_URL`"

Mfano wa kesi za majaribio (zilizopachikwa kwenye spec)

Hali	Pembejeo	Matokeo yanayotarajiwa
Usajili wa kawaida	email: `a@b.com`, nenosiri: `Pass1234`	`201`, rudisha `user_id`
Nenosiri fupi sana	nenosiri: `Ab1`	`400`, msimbo wa kosa `WEAK_PASSWORD`
Barua pepe tayari ipo	email hiyo hiyo	`409`, msimbo wa kosa `EMAIL_EXISTS`

Spec nzuri lazima kwanza iandike kesi za majaribio, kwa sababu AI inaweza kuzitumia moja kwa moja kuunda majaribio ya kipande, na baada ya kukamilisha uthibitishaji kiotomatiki.

2. Kanuni za msingi za kuandika Spec (Tofauti ya SMART)

Kanuni	Maelezo	Kinyume
Sahihi (Precise)	Tumia namba halisi, aina, masharti ya buliani, epuka "iwezekanavyo", "kwa kawaida"	❌ "Nenosiri liwe salama vya kutosha" → ✅ "Nenosiri lenye angalau herufi 8, lina herufi kubwa, ndogo, na namba"
Inayoweza kuthibitishwa (Verifiable)	Kila hitaji liweze kuhukumiwa kufaulu/kushindwa kwa jaribio la kiotomatiki au ukaguzi wa binadamu	❌ "Msimbo uwe mzuri" → ✅ "Utata wa utendaji (cyclomatic complexity) ≤ 10, hakuna vizuizi vya kanuni vinavyorudiwa"
Isiyo na utata (Unambiguous)	Istilahi sawa iwe na maana moja katika hati nzima, toa glossary ikibidi	❌ "Ikiwa mtumiaji hayupo, rudisha kosa" → ✅ "Mtumiaji hayupo → rudisha `404` na `{code: 'USER_NOT_FOUND'}`"
Kamili (Complete)	Inashughulikia njia ya furaha, njia zote za hitilafu, na mahitaji yasiyofanya kazi	❌ Imeandika tu hali za mafanikio → ✅ Inajumuisha muda wa kuisha kwa hifadhidata, ukosefu wa ruhusa, n.k.
Atomiki (Atomic)	Spec moja inaelezea kipengele kimoja cha kazi kinachoweza kutolewa kwa kujitegemea (ili AI ikamilishe kwa wakati mmoja)	❌ Tumia spec moja kuandika "mfumo mzima wa malipo" → ✅ Gawanya kuwa "tengeneza hati ya malipo", "thibitisha saini ya kurudi", "rudisha pesa"

3. Mchakato wa Spec Coding wakati wa kushirikiana na AI

Mwanadamu anaandika spec (muundo hapo juu, hasa andika kesi za majaribio na saini za vitendakazi).
Lisha spec mara moja kwa AI (usiweke mahitaji kwa njia ya mazungumzo yenye nyongeza, ili kuepuka "vibe pollution" ya kusudi).
AI itatoa msimbo + majaribio ya kipande (AI lazima itumie kesi za majaribio kwenye spec kuzalisha majaribio yanayotekelezeka).
Tekeleza majaribio: Ikiwa yote yamepita, nenda hatua inayofuata; vinginevyo, rekebisha spec au rekebisha msimbo moja kwa moja (hapa unaweza kuingia mzunguko mdogo, lakini rekodi mabadiliko).
Ukaguzi wa binadamu: Angalia kama kuna utendaji ulioongezwa nje ya spec (scope creep), angalia usalama/utendaji.
Unganisha: Weka hati ya spec na msimbo wa mwisho pamoja kwenye hazina, kama hati ya kudumu.

Mbinu muhimu: Spec kuwa msimbo - tumia spec.md + test_spec.py, ambapo faili ya majaribio inatokana moja kwa moja na mifano kwenye spec, ili baadaye unapobadilisha msimbo, unahitaji tu kuendesha majaribio ili kuthibitisha kama spec imevunjwa.

4. Madhara ya Spec nzuri (inaweza kutumika kama kigezo cha kukubalika)

Uhakika: Spec sawa ikitolewa kwa AI tofauti (au watu tofauti) hutoa utekelezaji unaofanana.
Uwezo wa kujaribiwa: Mara tu msimbo unapoandikwa, utaweza kuthibitisha kiotomatiki 90% ya usahihi.
Uwezo wa kutunzika: Baada ya miezi sita, mtu yeyote akisoma spec ataweza kuelewa dhamira ya muundo wa awali.
Gharama ndogo ya mawasiliano: Timu inapojadili, inajadili spec tu, si mistari mahususi ya msimbo.
Usalama/ubora uliojengewa ndani: Mahitaji ya usalama (kama maswali yaliyojibiwa kwa vigezo) na hali za mpaka zimeandikwa kwenye spec, AI lazima itii.

5. Mfano halisi wa Spec nzuri (toleo fupi)

# Spec: API ya usajili wa watumiaji

## Upeo
- Pokea email, nenosiri
- Haituma barua pepe ya uthibitishaji, haiangalii ukweli wa barua pepe

## Mkataba
POST /register
Content-Type: application/json
Ombi: { "email": string, "password": string }
Jibu 201: { "user_id": string }
Jibu 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Jibu 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Tabia
- email lazima izingatie muundo wa msingi wa RFC 5322 (a@b.c)
- nenosiri: urefu 8-20, angalau namba moja na herufi kubwa moja
- Tumia bcrypt kusimba kuhifadhi, gharama ya chumvi 10
- Kabla ya kuweka kwenye hifadhidata, ikiwa barua pepe tayari ipo → 409

## Kesi za majaribio (pembejeo -> msimbo wa hali+sehemu ya jibu)
| Pembejeo email | nenosiri | Inatarajiwa |
|----------------|----------|-------------|
| test@x.com | Pass1234  | 201, user_id ipo |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (barua pepe iliyopo) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Si za utendaji
- SQL lazima itumie maswali yaliyojibiwa kwa vigezo (zuia uingizaji)
- Kumbukumbu rekodi anwani ya IP ya asili ya usajili, usirekodi nenosiri
- Muda wa kujibu 95% ya maombi < 100ms (bila bcrypt)

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

Spec Coding bora = andika "maamuzi ya muundo" ya binadamu kuwa "kesi za majaribio + saini za aina + vikwazo vya tabia" vya mashine, huku AI ikijaza utekelezaji tu, na binadamu anadhibiti ubora na mwelekeo daima.