Interviuri AI Seria 16: Cum ar trebui să fie un spec coding bun?

Un Spec Coding bun (programare condusă de specificații) are ca esență transformarea „idelor vagi” în „contracte precise, verificabile și executabile”. Nu este vorba doar de a scrie un document, ci de a stabili un limbaj de comunicare fără ambiguitate între oameni și AI (sau între oameni). Mai jos voi prezenta cum arată un spec bun din patru dimensiuni: structura conținutului specificațiilor, principiile de redactare, fluxul de colaborare cu AI și validarea calității.

1. Structura standard a documentului de specificații (exemplu: modul funcțional)

Capitol	Conținut obligatoriu	Exemplu
1. Obiectiv și domeniu	Descrieți într-o propoziție ce faceți, specificați clar ce nu faceți	„Implementați API de înregistrare utilizator, nu include verificarea email-ului”
2. Contract de intrare/ieșire	Structură date, tipuri, câmpuri obligatorii/opționale, valori exemplu	Corp cerere `POST /register` `{email: string, password: string}`, răspuns `201` sau `400` cu cod de eroare
3. Comportament și logică	Reguli de afaceri, condiții limită, tranziții de stare	„Lungimea parolei 8-20 de caractere, cel puțin o cifră; dacă email-ul există deja, returnați `409`”
4. Gestionarea erorilor	Toate scenariile posibile de excepție și codurile/mesajele de eroare corespunzătoare	„Eșec la conectarea la baza de date → returnați `503`, nu expuneți stiva”
5. Cerințe non-funcționale	Performanță (timp răspuns < 200ms), securitate (interogări parametrizate), jurnalizare, observabilitate	„Toate SQL-urile trebuie să folosească compilare prealabilă; înregistrați `email` dar nu înregistrați `password`”
6. Cazuri de test (critice)	Cel puțin 3 intrări tipice + 2 intrări la limită/exceptionale, oferiți ieșirea așteptată	Vezi tabelul de mai jos
7. Dependențe și constrângeri	Ce biblioteci, versiuni, variabile de mediu	„Python 3.10+, FastAPI, variabila de mediu `DB_URL`”

Exemplu de cazuri de test (încorporate în spec)

Scenariu	Intrare	Ieșire așteptată
Înregistrare normală	email: `a@b.com`, pwd: `Pass1234`	`201`, returnează `user_id`
Parola prea scurtă	pwd: `Ab1`	`400`, cod eroare `WEAK_PASSWORD`
Email existent	Același email	`409`, cod eroare `EMAIL_EXISTS`

Un spec bun trebuie să scrie mai întâi cazuri de test, deoarece AI poate genera direct teste unitare pe baza acestora și le poate valida automat după finalizare.

2. Principii de bază pentru scrierea spec-ului (varianta SMART)

Principiu	Explicație	Contraexemplu
Precizie (Precise)	Folosiți numere specifice, tipuri, condiții booleene, evitați „pe cât posibil”, „de obicei”	❌ „Parola trebuie să fie suficient de sigură” → ✅ „Parola are cel puțin 8 caractere, conține majuscule, minuscule și cifre”
Verificabil (Verifiable)	Fiecare cerință poate fi verificată ca trecut/ne trecut prin testare automată sau verificare manuală	❌ „Codul trebuie să fie elegant” → ✅ „Complexitatea ciclomatică a funcției ≤ 10, fără blocuri de cod duplicate”
Fără ambiguitate (Unambiguous)	Aceiași termeni au același sens în întregul text, dați un glosar dacă este necesar	❌ „Dacă utilizatorul nu există, returnați o eroare” → ✅ „Utilizatorul nu există → returnați `404` și `{code: 'USER_NOT_FOUND'}`”
Complet (Complete)	Acoperiți calea fericită, toate căile de excepție, cerințele non-funcționale	❌ Ați scris doar scenarii de succes → ✅ Includeți timeout baze de date, permisiuni insuficiente etc.
Atomic (Atomic)	Un spec descrie un singur punct funcțional livrabil independent (pentru ca AI să îl finalizeze odată)	❌ Scrieți „întregul sistem de plată” într-un singur spec → ✅ Împărțiți în „generare factură”, „verificare semnătură apel invers”, „rambursare”

3. Fluxul de Spec Coding în colaborare cu AI

Omul scrie spec-ul (structura de mai sus, în special cazurile de test și semnăturile funcțiilor).
Transmiteți spec-ul odată către AI (nu adăugați cerințe prin dialog, pentru a evita contaminarea vibe).
AI produce cod + teste unitare (AI trebuie să genereze teste executabile conform cazurilor de test din spec).
Rulați testele: dacă toate trec, treceți la pasul următor; dacă nu, modificați spec-ul sau corectați codul direct (se poate intra într-un ciclu mic, dar înregistrați modificările).
Revizuire manuală: verificați dacă au fost introduse funcționalități în afara spec-ului (scope creep), verificați securitatea/performanța.
Finalizare: trimiteți documentul spec și codul final împreună în depozit, ca documentație permanentă.

Practică cheie: Codificarea spec-ului — folosiți spec.md + test_spec.py, unde fișierul de test provine direct din exemplele din spec, astfel încât la modificarea ulterioară a codului, rularea testelor verifică dacă spec-ul a fost încălcat.

4. Efectele unui spec bun (pot fi folosite ca criterii de acceptare)

Determinism: același spec dat unor AI diferite (sau persoane diferite) produce implementări similare.
Testabilitate: imediat după scrierea codului, 90% din corectitudine poate fi verificată automat.
Mentenabilitate: după șase luni, oricine citește spec-ul poate înțelege intenția de design inițială.
Cost redus de comunicare: în discuțiile echipei, se discută doar spec-ul, nu liniile de cod specifice.
Securitate/calitate integrată: cerințele de securitate (cum ar fi interogările parametrizate) și condițiile limită sunt specificate în spec, AI trebuie să le respecte.

5. Un exemplu de spec bun (versiune minimală)

# Spec: API de înregistrare utilizator

## Domeniu
- Primește email, password
- Nu trimite email de verificare, nu verifică autenticitatea email-ului

## Contract
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" }

## Comportament
- email trebuie să respecte formatul de bază RFC 5322 (a@b.c)
- password: lungime 8-20, cel puțin o cifră și o literă mare
- Se criptează cu bcrypt, cost sare 10
- Dacă înainte de stocare în baza de date se descoperă că email-ul există deja → 409

## Cazuri de test (Intrare -> Cod stare așteptat + câmp răspuns)
| email intrare | password | Așteptat |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id există |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (email existent) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Non-funcțional
- SQL trebuie să folosească interogări parametrizate (anti-injectare)
- Jurnalul înregistrează IP-ul sursei de înregistrare, nu înregistrează parola
- Timpul de răspuns pentru 95% din cereri < 100ms (fără bcrypt)

## Dependențe
- Python 3.10+, FastAPI, bcrypt, asyncpg

Un spec coding bun = scrieți „deciziile de design” ale omului ca „cazuri de test + semnături de tip + constrângeri de comportament” pentru mașină, lăsând AI-ul să se ocupe doar de implementare, în timp ce omul controlează întotdeauna calitatea și direcția.