Intervistë Seri AI 16: Si duhet të jetë një kodim i mirë specifikacioni?

Një Spec Coding (kodim i drejtuar nga specifikimet) i mirë, thelbi i tij është shndërrimi i "ideve të paqarta" në "marrëveshje të sakta, të verifikueshme dhe të ekzekutueshme". Nuk është thjesht shkrimi i një dokumenti, por krijimi i një gjuhe komunikimi pa paqartësi midis njerëzve dhe AI (ose midis njerëzve). Më poshtë do të jap një pamje të një spec-i të mirë nga katër dimensione: struktura e përmbajtjes së specifikimit, parimet e shkrimit, procesi i bashkëpunimit me AI, verifikimi i cilësisë.

1. Struktura standarde e dokumentit të specifikimit (me modul funksioni si shembull)

Kapitull	Përmbajtje e detyrueshme	Shembull
1. Qëllimi dhe fusha	Një fjali që shpjegon çfarë bën, qartëson çfarë nuk bën	"Implementoni API për regjistrim përdoruesi, nuk përfshin verifikim emaili"
2. Marrëveshja input/output	Struktura e të dhënave, llojet, fushat e detyrueshme/opsionale, vlerat shembull	`POST /register` trupi i kërkesës `{email: string, password: string}`, përgjigja `201` ose `400` me kod gabimi
3. Sjellja dhe logjika	Rregullat e biznesit, kushtet kufitare, ndryshimet e gjendjes	"Gjatësia e fjalëkalimit 8-20 karaktere, të paktën një numër; nëse email-i ekziston, kthe `409`"
4. Trajtimi i gabimeve	Të gjitha skenarët e mundshëm të përjashtimit dhe kodet/mesazhet përkatëse të gabimit	"Dështim i lidhjes me bazën e të dhënave → kthe `503`, mos ekspozoni stack-un"
5. Kërkesat jo-funksionale	Performanca (koha e përgjigjes < 200ms), siguria (query të parametrizuara), log, observueshmëria	"Të gjitha SQL-të duhet të përdorin precompile; regjistro `email` por jo `password`"
6. Raste testimi (kyç)	Të paktën 3 inpute tipike + 2 inpute kufitare/përjashtimore, jep outputin e pritur	Shih tabelën më poshtë
7. Varësitë dhe kufizimet	Cilat biblioteka përdoren, versioni, variablat e ambientit	"Python 3.10+, FastAPI, variabël ambienti `DB_URL`"

Shembull i rasteve të testimit (të integruara në spec)

Skenar	Input	Output i pritur
Regjistrim normal	email: `a@b.com`, pwd: `Pass1234`	`201`, kthen `user_id`
Fjalëkalim shumë i shkurtër	pwd: `Ab1`	`400`, kod gabimi `WEAK_PASSWORD`
Email tashmë ekziston	email i njëjtë si më sipër	`409`, kod gabimi `EMAIL_EXISTS`

Spec-i i mirë fillimisht shkruan rastet e testimit, sepse AI mund të gjenerojë testime njësie bazuar në to dhe të verifikojë automatikisht pas përfundimit.

2. Parimet thelbësore të shkrimit të Spec (variant SMART)

Parim	Shpjegim	Kundërshembull
I saktë (Precise)	Përdor numra konkretë, lloje, kushte boolean; shmang "sa më shumë", "zakonisht"	❌ "Fjalëkalimi duhet të jetë mjaft i sigurt" → ✅ "Fjalëkalimi të paktën 8 karaktere, përmban shkronjë të madhe, të vogël, numër"
I verifikueshëm (Verifiable)	Çdo kërkesë mund të vlerësohet si e kaluar/dështuar me testim automatik ose kontroll manual	❌ "Kodi duhet të jetë elegant" → ✅ "Kompleksiteti ciklik i funksionit ≤ 10, pa blloqe të përsëritura"
Pa paqartësi (Unambiguous)	I njëjti term ka kuptim të njëjtë në të gjithë tekstin; jep fjalor nëse nevojitet	❌ "Nëse përdoruesi nuk ekziston, kthe gabim" → ✅ "Përdoruesi nuk ekziston → kthe `404` dhe `{code: 'USER_NOT_FOUND'}`"
I plotë (Complete)	Mbulon rrugën e lumtur, të gjitha rrugët e përjashtimit, kërkesat jo-funksionale	❌ Shkruar vetëm skenarët e suksesit → ✅ Përfshin timeout të bazës së të dhënave, mungesë lejesh etj.
Atomik (Atomic)	Një spec përshkruan vetëm një funksion që mund të dorëzohet në mënyrë të pavarur (lehtëson AI-në ta përfundojë në një herë)	❌ Përdor një spec për "të gjithë sistemin e pagesave" → ✅ Ndaj në "gjenero faturë pagese", "verifiko nënshkrimin", "kthe para"

3. Procesi i Spec Coding-ut kur bashkëpunoni me AI

Njeriu shkruan spec-in (struktura e mësipërme, veçanërisht rastet e testimit dhe nënshkrimet e funksioneve).
I jep spec-in AI-të për një herë (mos shto kërkesa në mënyrë dialogu, shmang ndotjen e vibrit).
AI nxjerr kodin + testet e njësisë (AI duhet të gjenerojë teste të ekzekutueshme bazuar në rastet e testimit në spec).
Ekzekuto testet: nëse kalojnë të gjitha, kalo në hapin tjetër; nëse jo, modifiko spec-in ose korrigjo kodin direkt (në këtë pikë mund të hysh në një cikël të vogël, por regjistro ndryshimet).
Rishikim njerëzor: kontrollo nëse është futur funksionalitet jashtë spec-it (scope creep), kontrollo sigurinë/performancën.
Fikso: dërgo dokumentin e spec-it dhe kodin përfundimtar së bashku në depo, si dokumentacion të përhershëm.

Praktikë kyçe: Kodifikimi i spec-it – përdor spec.md + test_spec.py, ku skedari i testimit vjen direkt nga shembujt e spec-it, kështu që ndryshimet e mëvonshme në kod kërkojnë vetëm ekzekutimin e testeve për të verifikuar nëse spec-i është cenuar.

4. Efektet e një Spec-i të mirë (mund të shërbejnë si kritere pranimi)

Determinizëm: I njëjti spec i dhënë AI-ve të ndryshme (ose njerëzve të ndryshëm) prodhon implementime të ngjashme.
Testueshmëri: Pasi shkruhet kodi, menjëherë mund të verifikohet automatikisht 90% e saktësisë.
Mirëmbajtje: Pas gjashtë muajsh, kushdo që lexon spec-in mund të kuptojë qëllimin fillestar të dizajnit.
Kosto e ulët komunikimi: Gjatë diskutimeve në ekip, diskutohet vetëm spec-i, jo rreshtat konkretë të kodit.
Siguri/Cilësi e integruar: Kërkesat e sigurisë (si query të parametrizuara) dhe kushtet kufitare shkruhen në spec, AI duhet t'i respektojë.

5. Një shembull i Spec-it të mirë (version i thjeshtuar)

# Spec: 用户注册 API

## 范围
- 接收 email, password
- 不发送验证邮件，不检查邮箱真实性

## 契约
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" }

## 行为
- 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 |
| (已存在的邮箱) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## 非功能
- SQL 必须使用参数化查询（防注入）
- 日志记录注册来源 IP，不记录密码
- 响应时间 95% 请求 < 100ms (不含 bcrypt)

## 依赖
- Python 3.10+, FastAPI, bcrypt, asyncpg

Spec Coding i mirë = shndërrimi i "vendimeve të dizajnit" të njeriut në "raste testimi + nënshkrime tipash + kufizime sjelljeje" për makinën, duke lejuar AI-në të plotësojë vetëm implementimin, ndërsa njeriu kontrollon gjithmonë cilësinë dhe drejtimin.