AI seriýasy söhbetdeşlik 16: Gowy Spec Coding nähili bolmaly?

Gowy Spec Coding (Spesifikasiýa boýunça kodlamak), esasy maksady "düşnüksiz pikiri" "takyk, barlanyp bolýan we ýerine ýetirilip bolýan şertnama" öwürmekdir. Bu diňe bir resminama ýazmak däl, eýsem adam bilen AI (ýa-da adam bilen adam) arasynda düşnüksiz aragatnaşyk dilini döretmekdir. Aşakda spesifikasiýanyň mazmunynyň gurluşy, ýazuw ýörelgeleri, AI bilen hyzmatdaşlyk prosesi, hil tassyklamasy dört ölçegden gowy spec-iň nähili bolmalydygyny görkezýärin.

I. Spesifikasiýa resminamanyň standart gurluşy (funksional modul mysalynda)

Bölüm	Hökmany mazmun	Mysal
1. Maksat we çäk	Bir sözlem bilen näme edilýändigini, nämäniň edilmeýändigini aýdyň	"Ulanyjy hasaba alşy API-ni amala aşyr, e-poçta tassyklamasy goşulmaýar"
2. Giriş/çykyş şertnamasy	Maglumat gurluşy, görnüşi, hökmany/saýlama meýdanlar, mysal bahalar	`POST /register` sorag göwresi `{email: string, password: string}`, jogap `201` ýa-da `400` (ýalňyş kody bilen)
3. Hereket we logika	Iş düzgünleri, araçäk şertleri, ýagdaý geçişleri	"Parolyň uzynlygy 8-20 simwol, iň azyndan bir san; e-poçta bar bolsa `409` gaýtaryň"
4. Ýalňyşlygy işlemek	Mümkin bolan ähli adatdan daşary ýagdaýlar we degişli ýalňyş kodlar/hatlar	"Maglumat bazasy birikmesi şowsuz → `503` gaýtaryň, ýygnak açylmaýar"
5. Funksional däl talaplar	Öndürijilik (jogap wagty < 200ms), howpsuzlyk (parametrleşdirilen soraglar), log, gözegçilik edijilik	"Ähli SQL öňünden kompýuterlenmeli; `email` ýazga al, ýöne `password` ýazga alma"
6. Synag ýagdaýlary (möhüm)	Iň azyndan 3 adaty giriş + 2 araçäk/adatdan daşary giriş, garaşylýan çykyş	Aşakdaky jedweli serediň
7. Baglylyklar we çäklendirmeler	Haýsy kitaphanany, wersiýany, daşky gurşaw üýtgeýjisini ulanmaly	"Python 3.10+, FastAPI, daşky gurşaw üýtgeýjisi `DB_URL`"

Spec-iň içinde synag ýagdaýlarynyň mysaly

Ssenariý	Giriş	Garaşylýan çykyş
Adaty hasaba alma	email: `a@b.com`, pwd: `Pass1234`	`201`, `user_id` gaýtarylýar
Parol gysga	pwd: `Ab1`	`400`, ýalňyş kody `WEAK_PASSWORD`
E-poçta eýýäm bar	ýokardaky email	`409`, ýalňyş kody `EMAIL_EXISTS`

Gowy Spec ilki bilen synag ýagdaýlaryny ýazmaly, sebäbi AI olar boýunça gönüden-göni birlik synaglaryny döredip biler we gutarandan soň awtomatiki tassyklap biler.

II. Spec ýazmagyň esasy ýörelgeleri (SMART üýtgeşmesi)

Ýörelge	Düşündiriş	Garşy mysal
Takyk (Precise)	Anyk sanlar, görnüşler, şertler ulanyň; "mümkin", "adatça" ýaly sözlerden gaça duruň	❌ "Parol ýeterlik howpsuz bolmaly" → ✅ "Parol iň azyndan 8 simwol, uly harp, kiçi harp we san"
Barlanyp bolýan (Verifiable)	Her bir talaplar awtomatiki synag ýa-da el bilen barlap geçip/geçmeýänligini kesgitläp bolýar	❌ "Kod ýakymly bolmaly" → ✅ "Funksiýanyň sikliki çylşyrymlylygy ≤ 10, gaýtalanýan kod bölegi ýok"
Düşnüksiz (Unambiguous)	Bir termin ähli ýerde bir manyda ulanylýar; zerur bolsa glossary beriň	❌ "Ulanyjy ýok bolsa, ýalňyşlyk gaýtar" → ✅ "Ulanyjy ýok → `404` we `{code: 'USER_NOT_FOUND'}` gaýtar"
Doly (Complete)	Şatlykly ýoly, ähli adatdan daşary ýollary we funksional däl talaplary öz içine alýar	❌ Diňe üstünlikli ssenariý ýazyldy → ✅ Maglumat bazasynyň wagt aşmagy, ygtyýaryň ýetmezçiligi we ş.m.
Atomlaşdyrylan (Atomic)	Bir spec diňe bir özbaşdak gowşuryp bolýan funksiýany suratlandyrýar (AI-nyň bir gezekde tamamlamagy üçin)	❌ Bir spec bilen "töleg ulgamynyň ählisini" ýazmak → ✅ "Töleg buýrugyny döretmek", "Yzyna jaňy tassyklamak", "Yzyna gaýtarmak"

III. AI bilen hyzmatdaşlykda Spec Coding prosesi

Adam spec ýazýar (ýokardaky gurluş, esasanam synag ýagdaýlary we funksiýa imzasyny goşmak bilen).
Spek bir gezekde AI-a beriň (söhbetdeşlik görnüşinde talaplary goşmaň, vibe hapalanmagynyň öňüni alyň).
AI kod + birlik synaglaryny çykarýar (AI spec-däki synag ýagdaýlary boýunça ýerine ýetirip bolýan synaglary döretmeli).
Synaglary işlediň: Ählisi geçse, indiki ädime geçiň; geçmese, spec-i üýtgediň ýa-da kody göni düzediň (kiçi aýlawda bolup biler, ýöne üýtgeşmeler ýazga alynmaly).
Adam gözden geçirýär: Spec-den daşary funksiýalaryň goşulmandygyny (scope creep), howpsuzlyk/öndürijiligi barlaň.
Gurnama: Spec resminamasyny we soňky kody bilelikde ammara goýuň, hemişelik resminama hökmünde.

Esasy amalyýet: Spec-i kodlaşdyrmak — spec.md + test_spec.py ulanyň, synag faýly spec-däki mysallardan gönüden-göni alynýar. Şeýlelikde, soňrak kody üýtgedeniňizde diňe synaglary işledip, spec-iň bozulandygyny barlap bilersiňiz.

IV. Gowy Spec-iň getirýän täsiri (kabul ediş kriteriýasy hökmünde)

Kesgitlilik: Şol bir spec-i dürli AI-lara (ýa-da dürli adamlara) bereniňizde meňzeş amala aşyryşlar döreýär.
Synag edip bolýanlyk: Kody ýazan badyna awtomatiki usulda 90% dogrulygy tassyklap bolýar.
Goldaw edip bolýanlyk: Alty aýdan soň islendik adam spec-e seredip, başdaky dizaýn maksadyna düşünýär.
Aragatnaşyk çykdajylarynyň pesligi: Topar ara alyp maslahatlaşanda diňe spec barada gürleşýär, kod setirleri barada gürleşmeýär.
Howpsuzlyk/hil gurnalan: Howpsuzlyk talaplary (parametrleşdirilen soraglar ýaly) we araçäk şertleri spec-de ýazylýar, AI hökmany suratda berjaý etmeli.

V. Gowy Spec-iň mysaly (gysgaldylan görnüş)

# Spec: Ulanyjy hasaba alşy API

## Çäk
- email, password kabul edýär
- tassyklama e-poçta iberilmeýär, e-poçtanyň hakykylygy barlanylmaýar

## Şertnama
POST /register
Content-Type: application/json
Sorag: { "email": string, "password": string }
Jogap 201: { "user_id": string }
Jogap 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Jogap 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Hereket
- email RFC 5322 esasy formatyna laýyk bolmaly (a@b.c)
- password: uzynlygy 8-20, iň azyndan bir san we bir uly harp
- bcrypt bilen şifrlenip saklanmaly, duz bahasy 10
- Maglumat bazasyna ýazmazdan ozal email bar bolsa → 409

## Synag ýagdaýlary (giriş -> garaşylýan status kody + jogap meýdany)
| Giriş email | password | Garaşylýan |
|------------|----------|------------|
| test@x.com | Pass1234  | 201, user_id bar |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (eýýäm bar bolan email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Funksional däl
- SQL parametrleşdirilen soraglar bilen ýazylmaly (hüjümden goramak)
- Logda hasaba alşyň IP adresi ýazylmaly, password ýazylmaly däl
- Jogap wagty 95% soraglarda < 100ms (bcrypt hasaplamasyndan başga)

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

Gowy Spec Coding = adamyň "dizaýn kararlaryny" maşynyň "synag ýagdaýlary + görnüş imzasy + hereket çäklendirmeleri" görnüşinde ýazmak, şeýlelikde AI diňe amala aşyryşy doldurýar, adam bolsa hil we ugur boýunça gözegçilik edýär.