AI sorozat interjú 16: Milyen legyen egy jó specifikációvezérelt kódolás?

Egy jó Specifikációvezérelt kódolás (Spec Coding) lényege, hogy a „homályos ötleteket” „pontos, ellenőrizhető és végrehajtható szerződésekké” alakítsa. Nem csupán dokumentumot írni, hanem egy félreérthetetlen kommunikációs nyelvet létrehozni ember és AI (vagy ember és ember) között. Az alábbiakban a specifikáció tartalmi struktúrája, írási alapelvei, az AI-val való együttműködés folyamata és minőségellenőrzése szempontjából mutatom be, milyen egy jó spec.

I. A specifikációs dokumentum szabványos struktúrája (példa egy funkció modulra)

Fejezet	Kötelező tartalom	Példa
1. Cél és hatókör	Egy mondatban elmondani, mit csinál, és egyértelműen meghatározni, mit nem csinál	„Felhasználói regisztrációs API megvalósítása, e-mail megerősítés nélkül”
2. Bemeneti/kimeneti szerződés	Adatstruktúra, típus, kötelező/opcionális mezők, példaértékek	`POST /register` kérés törzs `{email: string, password: string}`, válasz `201` vagy `400` hibakóddal
3. Viselkedés és logika	Üzleti szabályok, határesetek, állapotátmenetek	„Jelszó hossza 8-20 karakter, legalább egy számot tartalmazzon; ha az e-mail már létezik, adjon vissza `409`-et”
4. Hibakezelés	Minden lehetséges kivételes forgatókönyv és a megfelelő hibakód/üzenet	„Adatbázis-kapcsolat meghiúsul → `503` visszaadása, verem nem mutatása”
5. Nem funkcionális követelmények	Teljesítmény (válaszidő < 200ms), biztonság (paraméterezett lekérdezések), naplózás, megfigyelhetőség	„Minden SQL előre lefordított utasításokat használjon; naplózni az `email`-t, de a `jelszót` nem”
6. Tesztesetek (kulcsfontosságú)	Legalább 3 tipikus bemenet + 2 határ/kivételes bemenet, várt kimenettel	Lásd az alábbi táblázatot
7. Függőségek és megszorítások	Milyen könyvtárakat, verziókat, környezeti változókat használ	„Python 3.10+, FastAPI, környezeti változó `DB_URL`”

Példa tesztesetek (a spec-ben beágyazva)

Forgatókönyv	Bemenet	Várt kimenet
Normál regisztráció	email: `a@b.com`, jelszó: `Pass1234`	`201`, `user_id` visszaadása
Túl rövid jelszó	jelszó: `Ab1`	`400`, hibakód `WEAK_PASSWORD`
E-mail már létezik	ugyanaz az email	`409`, hibakód `EMAIL_EXISTS`

A jó spec először a teszteseteket írja meg, mert az AI ezek alapján közvetlenül generálhat egységteszteket, amelyek automatikusan ellenőrzik a kódot.

II. A specifikáció írásának alapelvei (SMART változat)

Alapelv	Magyarázat	Ellenpélda
Pontos (Precise)	Konkrét számokat, típusokat, logikai feltételeket használjon; kerülje a „lehetőség szerint”, „általában” kifejezéseket	❌ „A jelszó legyen elég biztonságos” → ✅ „A jelszó legalább 8 karakter, tartalmazzon nagybetűt, kisbetűt és számot”
Ellenőrizhető (Verifiable)	Minden követelmény automatikus teszttel vagy manuális ellenőrzéssel eldönthető, hogy sikeres-e	❌ „A kód legyen elegáns” → ✅ „A ciklomatikus komplexitás ≤ 10, ne legyen ismétlődő kódblokk”
Félreérthetetlen (Unambiguous)	Ugyanaz a kifejezés az egész szövegben ugyanazt jelentse; szükség esetén glosszáriumot adjon	❌ „Ha a felhasználó nem létezik, adjon vissza hibát” → ✅ „Felhasználó nem létezik → `404` és `{code: 'USER_NOT_FOUND'}` visszaadása”
Teljes (Complete)	Fedje le a happy path-ot, minden kivételes utat és nem funkcionális követelményeket	❌ Csak a sikeres forgatókönyvet írja le → ✅ Tartalmazza az adatbázis-időtúllépést, hiányzó jogosultságokat stb.
Atomi (Atomic)	Egy specifikáció csak egy önállóan szállítható funkciópontot írjon le (hogy az AI egyszerre befejezhesse)	❌ Egy spec-ben leírni „a teljes fizetési rendszert” → ✅ Felbontani: „fizetési megbízás generálása”, „visszahívás aláírás-ellenőrzése”, „visszatérítés”

III. Specifikációvezérelt kódolás folyamata AI-val együttműködve

Ember írja a spec-et (a fenti struktúra, különösen a tesztesetek és függvényaláírások).
A spec-et egyszerre adja be az AI-nak (ne beszélgetés formájában adjon hozzá követelményeket, hogy elkerülje a vibe szennyeződést).
AI kimenet: kód + egységtesztek (az AI köteles a spec-ben szereplő tesztesetek alapján végrehajtható teszteket generálni).
Tesztek futtatása: ha minden sikeres, továbblépés; ha nem, módosítani kell a spec-et vagy közvetlenül javítani a kódot (ekkor kisebb ciklusba lehet lépni, de a változtatásokat rögzíteni kell).
Emberi felülvizsgálat: ellenőrizni, hogy nem került-e be a spec-en kívüli funkció (scope creep), valamint a biztonságot/teljesítményt.
Rögzítés: a spec dokumentumot és a végleges kódot együtt beadni a tárolóba, mint állandó dokumentációt.

Kulcsfontosságú gyakorlat: Spec kódosítása – használjon spec.md-t és test_spec.py-t, ahol a tesztfájl közvetlenül a spec-ben lévő példákból származik. Így később a kód módosításakor csak a teszteket kell futtatni, hogy ellenőrizze, a spec sértetlen-e.

IV. Egy jó spec által elért hatások (elfogadási kritériumként)

Determináltság: ugyanaz a spec különböző AI-oknak (vagy embereknek) hasonló megvalósítást eredményez.
Tesztelhetőség: a kód megírása után azonnal automatikusan ellenőrizhető a 90%-os helyesség.
Karbantarthatóság: fél év múlva bárki, aki megnézi a spec-et, megérti az eredeti tervezési szándékot.
Alacsony kommunikációs költség: a csapat csak a spec-ről beszél, nem a konkrét kódsorokról.
Beépített biztonság/minőség: a biztonsági követelmények (pl. paraméterezett lekérdezések) és határesetek a spec-ben szerepelnek, az AI köteles betartani.

V. Példa egy jó spec-re (minimalista)

# Spec: Felhasználói regisztrációs API

## Hatókör
- Email és jelszó fogadása
- Nem küld megerősítő e-mailt, nem ellenőrzi az e-mail valódiságát

## Szerződés
POST /register
Content-Type: application/json
Kérés: { "email": string, "password": string }
Válasz 201: { "user_id": string }
Válasz 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Válasz 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Viselkedés
- Az email-nek meg kell felelnie az RFC 5322 alapformátumnak (a@b.c)
- Jelszó: hossz 8-20, legalább egy számot és egy nagybetűt tartalmazzon
- Bcrypt-tel titkosítva tárolni, só költség 10
- Ha az adatbázisba mentés előtt kiderül, hogy az email már létezik → 409

## Tesztesetek (bemenet -> várt állapotkód+válaszmező)
| Bemenet email | Jelszó | Várt |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id létezik |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (már létező email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Nem funkcionális
- Az SQL-nek paraméterezett lekérdezéseket kell használnia (SQL injection ellen)
- Naplózni a regisztráció forrás IP-jét, a jelszót nem
- Válaszidő: a kérések 95%-a < 100ms (bcrypt nélkül)

## Függőségek
- Python 3.10+, FastAPI, bcrypt, asyncpg

Jó Spec Coding = az ember „tervezési döntéseit” a gép „teszteseteivé + típus aláírásává + viselkedési megszorításává” alakítani, így az AI csak a megvalósítással foglalkozik, miközben az ember mindvégig ellenőrzi a minőséget és az irányt.