AI viðtalsröð 16: Hvernig ætti góð spec kóðun að vera?

Góð Spec kóðun (forskriftardrifin forritun) snýst um að breyta „óskýrum hugmyndum“ í „nákvæman, sannanlegan og framkvæmanlegan samning“. Þetta snýst ekki bara um að skrifa skjal, heldur að koma á óvíslegu samskiptamáli milli manna og gervigreindar (eða manna emellan). Hér að neðan mun ég gefa dæmi um góða spec frá fjórum víddum: efnisuppbygging forskriftar, ritunarreglur, samvinnuferli við gervigreind, gæðastýring.

1. Uppbygging forskriftarskjals (með aðgerðareiningu sem dæmi)

Kafli	Áskilið innihald	Dæmi
1. Markmið og umfang	Ein setning sem útskýrir hvað er gert, skýrt hvað er ekki gert	„Útfæra notendaskráningar API, án tölvupóststaðfestingar“
2. Inn-/útgöngusamningur	Gagnaskipan, gerðir, áskilin/valfrjáls svið, dæmi	`POST /register` beiðnilykill `{email: string, password: string}`, svar `201` eða `400` með villukóða
3. Hegðun og rökfræði	Viðskiptareglur, jaðarskilyrði, ástandsumbreytingar	„Lykilorðslengd 8-20 stafir, að minnsta kosti einn tölustaf; tölvupóstur þegar til → skila `409`“
4. Villumeðhöndlun	Allar mögulegar undantekningar og samsvarandi villukóðar/skilaboð	„Gagnagrunnstenging mistókst → skila `503`, án stafls“
5. Óvirkar kröfur	Afköst (svartími < 200ms), öryggi (parameterized queries), annálar, sjáanleiki	„Allar SQL verða að nota forþýðingu; skrá `email` en ekki `password`“
6. Prófunardæmi (lykilatriði)	Að minnsta kosti 3 dæmigerð inntök + 2 jaðar/undantekningar inntök, með væntanlegu úttaki	Sjá töflu hér að neðan
7. Ósjálfstæði og skorður	Hvaða bókasöfn, útgáfur, umhverfisbreytur	„Python 3.10+, FastAPI, umhverfisbreyta `DB_URL`“

Prófunardæmi (innfellt í spec)

Atburðarás	Inntak	Væntanlegt úttak
Eðlileg skráning	email: `a@b.com`, pwd: `Pass1234`	`201`, skilar `user_id`
Lykilorð of stutt	pwd: `Ab1`	`400`, villukóði `WEAK_PASSWORD`
Tölvupóstur þegar til	sama email	`409`, villukóði `EMAIL_EXISTS`

Góð Spec verður fyrst að skrifa prófunardæmi, því gervigreind getur beint búið til einingapróf út frá þeim og sjálfvirkt staðfest að lokum.

2. Meginreglur við skrif á Spec (SMART afbrigði)

Meginregla	Skýring	Andstætt dæmi
Nákvæmni (Precise)	Notaðu tilteknar tölur, gerðir, Boolean skilyrði; forðastu „eins og mögulegt“ eða „venjulega“	❌ „Lykilorð verður að vera nóg öruggt“ → ✅ „Lykilorð að minnsta kosti 8 stafir, inniheldur hástaf, lágstaf, tölustaf“
Sannanleiki (Verifiable)	Hver krafa verður að vera hægt að staðfesta með sjálfvirkum prófum eða mannlegri skoðun sem staðist/mistókst	❌ „Kóðinn verður að vera glæsilegur“ → ✅ „Fylgiflækjustig falls ≤ 10, engir endurteknir kóðablokkir“
Óvísindi (Unambiguous)	Sama hugtak notast samkvæmt í öllum textanum, gefðu upp hugtakaskrá ef þörf krefur	❌ „Ef notandi er ekki til, skila villu“ → ✅ „Notandi ekki til → skila `404` og `{code: 'USER_NOT_FOUND'}`“
Heildstæði (Complete)	Ná yfir hamingjuferð, allar undantekningarleiðir, óvirkar kröfur	❌ Aðeins skrifað árangursatriði → ✅ Innifalið gagnagrunnstímaút, ófullnægjandi heimildir o.s.frv.
Atómísk (Atomic)	Ein spec lýsir aðeins einu sjálfstætt afhendanlegu aðgerðaratriði (þannig að gervigreind getur klárað það í einu)	❌ Nota eina spec til að skrifa „allt greiðslukerfi“ → ✅ Skipt í „búa til greiðsluseðil“, „kallbak undirskriftarstaðfesting“, „endurgreiðsla“

3. Spec Kóðunarferli við samvinnu við gervigreind

Maður skrifar spec (ofangreind uppbygging, sérstaklega prófunardæmi og fallundirskriftir).
Fóðra spec strax inn í gervigreind (ekki til viðbótarspjallskrár, forðastu „vibe“ mengun).
Gervigreind framleiðir kóða + einingapróf (gervigreind verður að búa til keyranleg próf samkvæmt prófunardæmum í spec).
Keyra próf: Ef öll standast, farðu í næsta skref; ef ekki, lagfærðu spec eða kóða beint (hér má fara í smár lykkjur, en skráðu breytingar).
Mannleg skoðun: Athuga hvort einhverjar aðgerðir utan spec (scope creep) hafi verið bættar við, athuga öryggi/afköst.
Frysta: Skilaðu spec skjalinu og lokakóðanum saman í geymslu sem varanlegt skjal.

Lykilaðferð: Spec sem kóði – notaðu spec.md + test_spec.py, þar sem prófunarskráin kemur beint úr dæmum í spec, þannig að seinna við breytingar á kóða þarf bara að keyra próf til að staðfesta að spec sé ekki brotið.

4. Áhrif góðs Spec (getur verið viðmið fyrir samþykki)

Ákveðni: Sama spec gefið mismunandi gervigreind (eða mismunandi fólki) framleiðir svipaða útfærslu.
Prófanleiki: Eftir að kóði er skrifaður er hægt að sjálfvirkt staðfesta 90% réttleika.
Viðhaldanleiki: Eftir hálft ár getur hver sem er lesið spec og skilið upphaflega hönnunarhugmynd.
Lítill samskiptakostnaður: Liðið ræðir aðeins spec, ekki einstakar kóðalínur.
Öryggi/gæði innbyggð: Öryggiskröfur (eins og parameterized queries) og jaðarskilyrði skrifuð í spec, gervigreind verður að fylgja.

5. Dæmi um gott Spec (einangruð útgáfa)

# Spec: Notendaskráningar API

## Umfang
- Tekur við email, password
- Sendir ekki staðfestingarpóst, athugar ekki raunveruleika tölvupósts

## Samningur
POST /register
Content-Type: application/json
Beiðni: { "email": string, "password": string }
Svar 201: { "user_id": string }
Svar 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Svar 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Hegðun
- email verður að vera í samræmi við RFC 5322 grunnform (a@b.c)
- password: lengd 8-20, að minnsta kosti einn tölustafur og einn hástafur
- Notaðu bcrypt til dulritunar, salt kostnaður 10
- Ef email finnst þegar til fyrir gagnagrunnsskráningu → 409

## Prófunardæmi (inntak -> væntanleg stöðukóði+svarsvið)
| Inntak email | password | Vænting |
|------------|----------|------|
| test@x.com | Pass1234  | 201, user_id til |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (tölvupóstur sem er þegar til) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Óvirkar kröfur
- SQL verður að nota parameterized queries (varnir gegn innspýtingu)
- Annálar skrá upprunalega IP-tölu skráningar, ekki lykilorð
- Svartími 95% beiðna < 100ms (án bcrypt)

## Ósjálfstæði
- Python 3.10+, FastAPI, bcrypt, asyncpg

Góð Spec kóðun = að breyta „hönnunarákvörðunum“ manna í „prófunardæmi + gerðarundirskriftir + hegðunarskorður“ fyrir vélina, þannig að gervigreind sér um útfærsluna, en maður heldur alltaf stjórn á gæðum og stefnu.