← 返回列表

AI Müsahibə Seriyası 16: Yaxşı bir Spec Kodlaşdırması necə olmalıdır?

AI Knowledge AI Interview

Yaxşı bir Spec Kodlaşdırması (spesifikasiyaya əsaslanan proqramlaşdırma), əsas məqsədi "qeyri-dəqiq fikirləri" "dəqiq, yoxlanıla bilən və icra edilə bilən müqavilələrə" çevirməkdir. Bu, sadəcə sənəd yazmaq deyil, insan və AI (və ya insanlar arasında) anlaşılmazlığa yer qoymayan ünsiyyət dili qurmaqdır. Aşağıda spesifikasiyanın məzmun strukturu, yazı prinsipləri, AI ilə əməkdaşlıq prosesi və keyfiyyət doğrulaması olmaqla dörd ölçüdə yaxşı bir spec-in necə olmasını göstərəcəyəm.

1. Spesifikasiya Sənədinin Standart Strukturu (Funksional Modul Nümunəsi)

Bölmə Məcburi Məzmun Nümunə
1. Məqsəd və Əhatə Dairəsi Bir cümlə ilə nə edildiyini, nəyin edilmədiyini aydınlaşdırın "İstifadəçi qeydiyyatı API-ni həyata keçir, e-poçt doğrulaması daxil deyil"
2. Giriş/Çıxış Müqaviləsi Məlumat strukturu, tip, məcburi/isteğe bağlı sahələr, nümunə dəyərlər POST /register sorğu gövdəsi {email: string, password: string}, cavab 201 və ya 400 xəta kodu ilə
3. Davranış və Məntiq Biznes qaydaları, sərhəd şərtləri, vəziyyət keçidləri "Şifrə uzunluğu 8-20 simvol, ən azı bir rəqəm olmalı; e-poçt mövcud olduqda 409 qaytarın"
4. Xəta İdarəetməsi Bütün mümkün anomaliya ssenariləri və müvafiq xəta kodları/mesajları "Verilənlər bazası əlaqəsi uğursuz oldu → 503 qaytarın, stack trace ifşa etməyin"
5. Qeyri-Funksional Tələblər Performans (cavab müddəti < 200ms), təhlükəsizlik (parametrləşdirilmiş sorğular), loglama, müşahidə ediləbilirlik "Bütün SQL-lər əvvəlcədən tərtib edilməlidir; email-i qeyd edin, password-i qeyd etməyin"
6. Test Halları (Əsas) Ən azı 3 tipik giriş + 2 sərhəd/anomaliya girişi, gözlənilən çıxışı verin Aşağıdakı cədvələ baxın
7. Asılılıqlar və Məhdudiyyətlər Hansı kitabxana, versiya, mühit dəyişənləri istifadə olunur "Python 3.10+, FastAPI, mühit dəyişəni DB_URL"

Spec daxilində Test Halları Nümunəsi

Ssenari Giriş Gözlənilən Çıxış
Normal qeydiyyat email: a@b.com, şifrə: Pass1234 201, user_id qaytarır
Şifrə çox qısa şifrə: Ab1 400, xəta kodu WEAK_PASSWORD
E-poçt artıq mövcuddur eyni email 409, xəta kodu EMAIL_EXISTS

Yaxşı Spec əvvəlcə test hallarını yazmalıdır, çünki AI onlara əsasən birbaşa vahid testlər yarada və tamamlandıqdan sonra avtomatik yoxlaya bilər.

2. Spec Yazmağın Əsas Prinsipləri (SMART Varyasiyası)

Prinsip İzah Əks Nümunə
Dəqiq (Precise) Xüsusi rəqəmlər, tiplər, boolean şərtlər istifadə edin; "mümkün qədər", "adətən" kimi sözlərdən çəkinin ❌ "Şifrə kifayət qədər təhlükəsiz olmalıdır" → ✅ "Şifrə ən azı 8 simvol, böyük hərf, kiçik hərf və rəqəm olmalıdır"
Yoxlanıla bilən (Verifiable) Hər bir tələb avtomatik test və ya əl ilə yoxlama ilə keçid/uğursuzluq olaraq təyin oluna bilməlidir ❌ "Kod zərif olmalıdır" → ✅ "Funksiyanın siklik mürəkkəbliyi ≤ 10, təkrarlanan kod blokları olmamalıdır"
Anlaşılmazlığa Yer Qoymayan (Unambiguous) Eyni termin bütün mətndə eyni məna daşımalı, lazım gəldikdə lüğət verin ❌ "İstifadəçi mövcud deyilsə, xəta qaytarın" → ✅ "İstifadəçi mövcud deyil → 404 və {code: 'USER_NOT_FOUND'} qaytarın"
Tam (Complete) Xoş yol, bütün anomaliya yolları, qeyri-funksional tələbləri əhatə edir ❌ Yalnız uğur ssenariləri yazılıb → ✅ Verilənlər bazası vaxt aşımı, icazə çatışmazlığı və s. daxildir
Atomik (Atomic) Bir spec yalnız müstəqil çatdırıla bilən bir funksiyanı təsvir edir (AI-nin bir dəfədə tamamlaması üçün əlverişli) ❌ Bir spec ilə "bütün ödəniş sistemi" yazılır → ✅ "Ödəniş sifarişi yarat", "Geri çağırış imzasını doğrula", "Geri ödəmə" kimi parçalanır

3. AI ilə Əməkdaşlıqda Spec Kodlaşdırma Prosesi

  1. İnsan spec yazır (yuxarıdakı struktur, xüsusilə test halları və funksiya imzaları yaxşı yazılmalıdır).
  2. Spec-i bir dəfəyə AI-ya verin (dialoq şəklində tələblər əlavə etməyin, vibe çirklənməsindən çəkinin).
  3. AI kod + vahid testlər çıxarır (AI spec-dəki test hallarına əsasən icra edilə bilən testlər yaratmalıdır).
  4. Testləri işə salın: hamısı keçərsə, növbəti mərhələyə keçin; keçməzsə, spec-i düzəldin və ya birbaşa kodu dəyişin (bu zaman kiçik dövrə girə bilərsiniz, lakin dəyişiklikləri qeyd edin).
  5. İnsan tərəfindən yoxlama: spec-in xaricində funksionallığın əlavə olunub-olunmadığını (scope creep), təhlükəsizlik/performansı yoxlayın.
  6. Möhkəmləndirmə: spec sənədini və son kodu birlikdə depoya yerləşdirin, daimi sənəd kimi saxlayın.

Əsas təcrübə: Spec-in kodlaşdırılması — spec.md + test_spec.py istifadə edin, test faylı birbaşa spec-dəki nümunələrdən gəlir. Beləliklə, sonradan kodu dəyişdikdə yalnız testləri işə salmaqla spec-in pozulub-pozulmadığını yoxlamaq olar.

4. Yaxşı Spec-in Gətirdiyi Nəticələr (Qəbul Kriteriyaları kimi istifadə edilə bilər)

  • Müəyyənlik: Eyni spec müxtəlif AI-lara (və ya müxtəlif insanlara) verildikdə oxşar tətbiqlər əldə edilir.
  • Test Edilə bilənlik: Kod yazılan kimi dərhal avtomatik olaraq 90% düzgünlük yoxlanıla bilər.
  • Davamlılıq: Altı ay sonra hər kəs spec-ə baxaraq ilkin dizayn məqsədini başa düşə bilər.
  • Aşağı Ünsiyyət Xərci: Komanda müzakirələrində yalnız spec müzakirə edilir, konkret kod sətirləri deyil.
  • Təhlükəsizlik/Keyfiyyət Daxili: Təhlükəsizlik tələbləri (məsələn, parametrləşdirilmiş sorğular) və sərhəd şərtləri spec-də yazılır, AI onlara riayət etməlidir.

5. Yaxşı Spec Nümunəsi (Çox Sadə Versiya)

# Spec: İstifadəçi Qeydiyyatı API

## Əhatə Dairəsi
- email, password qəbul edir
- Doğrulama e-poçtu göndərmir, e-poçtun həqiqiliyini yoxlamır

## Müqavilə
POST /register
Content-Type: application/json
Sorğu: { "email": string, "password": string }
Cavab 201: { "user_id": string }
Cavab 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Cavab 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Davranış
- email RFC 5322 əsas formatına uyğun olmalıdır (a@b.c)
- password: uzunluq 8-20, ən azı bir rəqəm və bir böyük hərf
- bcrypt ilə şifrələnmiş saxlanılır, duz xərci 10
- Verilənlər bazasına yazmadan əvvəl email mövcuddursa → 409

## Test Halları (giriş -> gözlənilən status kodu+cavab sahəsi)
| Giriş email | password | Gözlənilən |
|-------------|----------|------------|
| test@x.com | Pass1234  | 201, user_id mövcuddur |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad         | Pass1234  | 400, INVALID_EMAIL |
| (mövcud email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Qeyri-Funksional
- SQL-lər parametrləşdirilmiş sorğu ilə yazılmalıdır (injection-ın qarşısı)
- Loglarda qeydiyyat mənbə IP-si qeyd edilir, şifrə qeyd edilmir
- Cavab müddəti 95% sorğu < 100ms (bcrypt istisna olmaqla)

## Asılılıqlar
- Python 3.10+, FastAPI, bcrypt, asyncpg

Yaxşı Spec Kodlaşdırması = İnsanın "dizayn qərarlarını" maşının "test halları + tip imzaları + davranış məhdudiyyətləri" olaraq yazmaq və AI-ya yalnız tətbiqi doldurmaq qalır, insan isə hər zaman keyfiyyət və istiqamətə nəzarət edir.

评论

暂无已展示的评论。

发表评论（匿名）