AI-ს ინტერვიუების სერია 16: როგორი უნდა იყოს კარგი spec coding?

კარგი Spec Coding (სპეციფიკაციაზე ორიენტირებული პროგრამირება) მთავარია „ბუნდოვანი იდეის“ „ზუსტ, შესამოწმებელ და შესრულებად კონტრაქტად“ გარდაქმნა. ეს არ არის მხოლოდ დოკუმენტის დაწერა, არამედ ადამიანსა და AI-ს (ან ადამიანებს შორის) ორაზროვნების გარეშე კომუნიკაციის ენის შექმნა. ქვემოთ მე განვიხილავ სპეციფიკაციის შინაარსის სტრუქტურას, წერის პრინციპებს, AI-სთან თანამშრომლობის ნაკადს და ხარისხის შემოწმებას ოთხი განზომილებიდან, რათა ვაჩვენო როგორი უნდა იყოს კარგი spec.

1. სპეციფიკაციის დოკუმენტის სტანდარტული სტრუქტურა (ფუნქციონალური მოდულის მაგალითზე)

თავი	სავალდებულო შინაარსი	მაგალითი
1. მიზანი და ფარგლები	ერთი წინადადება, რას აკეთებს, ნათლად მიუთითეთ რას არ აკეთებს	„მომხმარებლის რეგისტრაციის API, ელ.ფოსტის დადასტურების გარეშე“
2. შეტანის/გამოტანის კონტრაქტი	მონაცემთა სტრუქტურა, ტიპები, სავალდებულო/არასავალდებულო ველები, მაგალითი მნიშვნელობები	`POST /register` მოთხოვნის სხეული `{email: string, password: string}`, პასუხი `201` ან `400` შეცდომის კოდით
3. ქცევა და ლოგიკა	ბიზნეს წესები, საზღვრითი პირობები, მდგომარეობების გარდაქმნა	„პაროლი 8-20 სიმბოლო, მინიმუმ ერთი ციფრი; ელ.ფოსტა უკვე არსებობს → 409“
4. შეცდომების დამუშავება	ყველა შესაძლო გამონაკლისი სცენარი და შესაბამისი შეცდომის კოდი/შეტყობინება	„მონაცემთა ბაზის კავშირის წარუმატებლობა → 503, არ გამოაჩინოთ stack trace“
5. არაფუნქციონალური მოთხოვნები	შესრულება (პასუხის დრო < 200ms), უსაფრთხოება (პარამეტრიზებული შეკითხვები), ჟურნალირება, ხილვადობა	„ყველა SQL უნდა იყოს წინასწარ კომპილირებული; ჩაწერეთ `email` მაგრამ არ ჩაწეროთ `password`“
6. ტესტის შემთხვევები (მნიშვნელოვანი)	მინიმუმ 3 ტიპიური შეტანა + 2 საზღვრითი/გამონაკლისი შეტანა, მოსალოდნელი გამოტანით	იხ. ქვემოთ მოცემული ცხრილი
7. დამოკიდებულებები და შეზღუდვები	რა ბიბლიოთეკები, ვერსიები, გარემოს ცვლადები	„Python 3.10+, FastAPI, გარემოს ცვლადი `DB_URL`“

ტესტის შემთხვევების მაგალითი (spec-ში ჩაშენებული)

სცენარი	შეტანა	მოსალოდნელი გამოტანა
ნორმალური რეგისტრაცია	email: `a@b.com`, pwd: `Pass1234`	`201`, უკან `user_id`
პაროლი ძალიან მოკლე	pwd: `Ab1`	`400`, შეცდომის კოდი `WEAK_PASSWORD`
ელ.ფოსტა უკვე არსებობს	იგივე email	`409`, შეცდომის კოდი `EMAIL_EXISTS`

კარგი Spec ჯერ ტესტის შემთხვევები უნდა დაწეროს, რადგან AI-ს შეუძლია მათზე დაყრდნობით პირდაპირ გენერირება მოახდინოს ერთეულ ტესტებზე, რომლებიც დასრულების შემდეგ ავტომატურად შემოწმდება.

2. Spec-ის წერის ძირითადი პრინციპები (SMART-ის ვარიანტი)

პრინციპი	ახსნა	ანტი-მაგალითი
ზუსტი (Precise)	გამოიყენეთ კონკრეტული რიცხვები, ტიპები, ლოგიკური პირობები, მოერიდეთ „რაც შეიძლება“, „ჩვეულებრივ“	❌ „პაროლი უნდა იყოს საკმარისად უსაფრთხო“ → ✅ „პაროლი მინიმუმ 8 სიმბოლო, შეიცავდეს დიდ ასოს, პატარა ასოს და ციფრს“
შესამოწმებელი (Verifiable)	თითოეული მოთხოვნა შეიძლება შემოწმდეს ავტომატური ტესტით ან ხელით შემოწმებით, რათა დადგინდეს წარმატება/მარცხი	❌ „კოდი უნდა იყოს ელეგანტური“ → ✅ „ფუნქციის ციკლომატური სირთულე ≤ 10, არ იყოს განმეორებადი კოდის ბლოკები“
ორაზროვნების გარეშე (Unambiguous)	იგივე ტერმინი მთელ ტექსტში ერთნაირი მნიშვნელობით, საჭიროების შემთხვევაში მიაწოდეთ გლოსარიუმი	❌ „თუ მომხმარებელი არ არსებობს, დაბრუნდით შეცდომა“ → ✅ „მომხმარებელი არ არსებობს → 404 და `{code: 'USER_NOT_FOUND'}`“
სრული (Complete)	მოიცავს ბედნიერ გზას, ყველა გამონაკლის გზას, არაფუნქციონალურ მოთხოვნებს	❌ მხოლოდ წარმატებული სცენარია დაწერილი → ✅ მოიცავს მონაცემთა ბაზის ტაიმაუტს, უფლებების ნაკლებობას და ა.შ.
ატომური (Atomic)	ერთი spec აღწერს მხოლოდ ერთ დამოუკიდებლად მიწოდებად ფუნქციას (რათა AI-მ ერთხელ დაასრულოს)	❌ ერთი spec-ით „მთელი გადახდის სისტემა“ → ✅ გაყოფა „გადახდის ბილეთის გენერაცია“, „callback-ის ხელმოწერის შემოწმება“, „თანხის დაბრუნება“

3. Spec Coding-ის ნაკადი AI-სთან თანამშრომლობისას

ადამიანი წერს spec-ს (ზემოთ მოცემული სტრუქტურა, განსაკუთრებით ტესტის შემთხვევები და ფუნქციის ხელმოწერები).
spec ერთბაშად მიეწოდება AI-ს (არა დიალოგური დამატებები, რათა თავიდან იქნას აცილებული vibe-ის დაბინძურება).
AI გამოსცემს კოდს + ერთეულ ტესტებს (AI უნდა მიჰყვეს spec-ში მოცემულ ტესტის შემთხვევებს და შექმნას შესრულებადი ტესტები).
ტესტების გაშვება: თუ ყველა გაივლის, გადადით შემდეგ საფეხურზე; თუ არა, შეცვალეთ spec ან პირდაპირ შეასწორეთ კოდი (ამ შემთხვევაში შეგიძლიათ შეხვიდეთ მცირე ციკლში, მაგრამ ჩაწერეთ ცვლილებები).
ადამიანის მიერ განხილვა: შეამოწმეთ, შეყვანილია თუ არა spec-ის გარეშე ფუნქციები (scope creep), შეამოწმეთ უსაფრთხოება/შესრულება.
დაფიქსირება: spec-ის დოკუმენტი და საბოლოო კოდი ერთად ატვირთეთ რეპოზიტორიაში, როგორც მუდმივი დოკუმენტაცია.

მთავარი პრაქტიკა: Spec-ის კოდად გადაქცევა – გამოიყენეთ spec.md + test_spec.py, სადაც ტესტის ფაილი პირდაპირ spec-ის მაგალითებიდან მოდის, ასე რომ კოდის შემდგომი შეცვლისას მხოლოდ ტესტების გაშვებით შეგიძლიათ შეამოწმოთ, დაირღვა თუ არა spec-ი.

4. კარგი Spec-ის ეფექტები (შეიძლება გახდეს მიღების კრიტერიუმი)

განსაზღვრულობა: იგივე spec-ი სხვადასხვა AI-ს (ან სხვადასხვა ადამიანს) მსგავს იმპლემენტაციას აწარმოებს.
ტესტირებადობა: კოდის დაწერისთანავე შესაძლებელია 90% სისწორის ავტომატურად შემოწმება.
შენახულობა: ნახევარი წლის შემდეგ ვინმეს, ვინც spec-ს კითხულობს, შეუძლია გაიგოს თავდაპირველი დიზაინის განზრახვა.
დაბალი კომუნიკაციის ღირებულება: გუნდური დისკუსიის დროს მხოლოდ spec-ზე საუბრობენ, კონკრეტულ კოდის ხაზებზე არა.
უსაფრთხოება/ხარისხი ჩაშენებული: უსაფრთხოების მოთხოვნები (როგორიცაა პარამეტრიზებული შეკითხვები) და საზღვრითი პირობები spec-შია მითითებული, AI ვალდებულია დაიცვას ისინი.

5. კარგი Spec-ის მაგალითი (მინიმალური)

# Spec: მომხმარებლის რეგისტრაციის API

## ფარგლები
- იღებს email-ს, password-ს
- არ აგზავნის დადასტურების წერილს, არ ამოწმებს ელ.ფოსტის ნამდვილობას

## კონტრაქტი
POST /register
Content-Type: application/json
მოთხოვნა: { "email": string, "password": string }
პასუხი 201: { "user_id": string }
პასუხი 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
პასუხი 409: { "code": "EMAIL_ALREADY_EXISTS" }

## ქცევა
- email უნდა შეესაბამებოდეს RFC 5322 ძირითად ფორმატს (a@b.c)
- password: სიგრძე 8-20, მინიმუმ ერთი ციფრი და ერთი დიდი ასო
- გამოიყენეთ bcrypt დაშიფვრა შესანახად, მარილის ღირებულება 10
- თუ მონაცემთა ბაზაში ჩაწერამდე აღმოჩნდა, რომ email უკვე არსებობს → 409

## ტესტის შემთხვევები (შეტანა -> მოსალოდნელი სტატუსის კოდი+პასუხის ველი)
| შეტანა email | password | მოსალოდნელი |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id არსებობს |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (უკვე არსებული email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## არაფუნქციონალური
- SQL უნდა იყოს პარამეტრიზებული (ინექციის თავიდან ასაცილებლად)
- ჟურნალში ჩაწერეთ რეგისტრაციის წყაროს IP, არ ჩაწეროთ password
- პასუხის დრო 95% მოთხოვნის < 100ms (bcrypt-ის გარეშე)

## დამოკიდებულებები
- Python 3.10+, FastAPI, bcrypt, asyncpg

კარგი Spec Coding = ადამიანის „დიზაინის გადაწყვეტილებების“ მანქანის „ტესტის შემთხვევებად + ტიპის ხელმოწერებად + ქცევის შეზღუდვებად“ გარდაქმნა, რათა AI მხოლოდ იმპლემენტაციის შევსებაზე იყოს პასუხისმგებელი, ხოლო ადამიანი მუდმივად აკონტროლებდეს ხარისხსა და მიმართულებას.