AI-serie interview 16: Hvordan bør en god spec-kodning være?

En god Spec-kodning (specifikationsdrevet programmering) handler i bund og grund om at omdanne 'vage ideer' til 'præcise, verificerbare og eksekverbare kontrakter'. Det handler ikke kun om at skrive et dokument, men om at etablere et entydigt kommunikationssprog mellem mennesker og AI (eller mellem mennesker). Nedenfor vil jeg give et billede af en god spec ud fra fire dimensioner: specifikationens indholdsstruktur, skriveprincipper, samarbejdsproces med AI og kvalitetsverifikation.

1. Standard struktur for specifikationsdokument (med funktionsmodul som eksempel)

Afsnit	Obligatorisk indhold	Eksempel
1. Mål og omfang	En sætning, der forklarer, hvad der skal gøres, og tydeligt angiver hvad der ikke skal gøres	“Implementere brugerregistrerings-API, inkluderer ikke e-mail-verifikation”
2. Input/output-kontrakt	Datastruktur, type, obligatoriske/valgfrie felter, eksempelværdier	`POST /register` request body `{email: string, password: string}`, svar `201` eller `400` med fejlkode
3. Adfærd og logik	Forretningsregler, grænsetilfælde, tilstandsovergange	“Password længde 8-20 tegn, mindst ét tal; hvis e-mail allerede findes, returnér `409`”
4. Fejlhåndtering	Alle mulige undtagelsesscenarier og tilsvarende fejlkode/meddelelse	“Databaseforbindelse mislykkedes → returnér `503`, ingen staksporing”
5. Ikke-funktionelle krav	Ydeevne (svartid < 200 ms), sikkerhed (parameteriserede forespørgsler), logning, observerbarhed	“Alle SQL skal bruge forberedte udsagn; log `email` men ikke `password`”
6. Testcases (afgørende)	Mindst 3 typiske input + 2 grænse/undtagelsesinput, angiv forventet output	Se nedenstående tabel
7. Afhængigheder og begrænsninger	Hvilke biblioteker, versioner, miljøvariabler	“Python 3.10+, FastAPI, miljøvariabel `DB_URL`”

Eksempel på testcases (indlejret i spec)

Scenario	Input	Forventet output
Normal registrering	email: `a@b.com`, pwd: `Pass1234`	`201`, returnér `user_id`
Password for kort	pwd: `Ab1`	`400`, fejlkode `WEAK_PASSWORD`
E-mail allerede eksisterende	Samme e-mail som ovenfor	`409`, fejlkode `EMAIL_EXISTS`

En god spec skal først skrive testcases, fordi AI direkte kan generere enhedstest ud fra dem og automatisk verificere, når de er færdige.

2. Kerne principper for at skrive spec (SMART variant)

Princip	Forklaring	Modsat eksempel
Præcis	Brug specifikke tal, typer, boolske betingelser, undgå 'så vidt muligt', 'normalt'	❌ “Password skal være sikkert nok” → ✅ “Password mindst 8 tegn, indeholder stort, småt og tal”
Verificerbar	Hvert krav kan bestemmes bestået/fejlet via automatisk test eller manuel inspektion	❌ “Koden skal være elegant” → ✅ “Funktion cyklomatisk kompleksitet ≤ 10, ingen duplikerede kodeblokke”
Entydig	Samme term har ensartet betydning i hele teksten, om nødvendigt angiv ordliste	❌ “Hvis brugeren ikke findes, returnér en fejl” → ✅ “Bruger findes ikke → returnér `404` og `{code: 'USER_NOT_FOUND'}`”
Komplet	Dækker happy path, alle undtagelsesstier, ikke-funktionelle krav	❌ Skrev kun succes-scenario → ✅ Inkluderer database timeout, utilstrækkelige rettigheder osv.
Atomisk	En spec beskriver kun én uafhængigt leverbar funktion (for at AI kan gennemføre det på én gang)	❌ Brug én spec til at skrive 'hele betalingssystemet' → ✅ Opdel i 'generer betalingsordre', 'callback signaturverifikation', 'refusion'

3. Spec kodningsflow ved samarbejde med AI

Mennesket skriver spec (ovenstående struktur, især testcases og funktionssignaturer).
Giv spec'en til AI på én gang (undgå dialogbaseret tilføjelse af krav for at undgå 'vibe'-forurening).
AI udskriver kode + enhedstest (AI skal generere eksekverbare tests i henhold til testcases i spec'en).
Kør testene: Hvis alle bestås, gå til næste trin; hvis ikke, modificer spec'en eller ret koden direkte (her kan man gå ind i en lille cyklus, men registrer ændringer).
Manuel gennemgang: Kontrollér, om der er introduceret funktioner ud over spec'en (scope creep), kontrollér sikkerhed/ydelse.
Fastfrysning: Indsend spec-dokumentet og den endelige kode til repository som permanent dokumentation.

Nøglepraksis: Spec-kodificering – brug spec.md + test_spec.py, hvor testfilen direkte kommer fra eksemplerne i spec'en, så man senere ved ændring af kode blot skal køre testene for at verificere, om spec'en er brudt.

4. Effekter af en god spec (kan bruges som acceptkriterier)

Determinisme: Samme spec til forskellige AI (eller forskellige mennesker) giver lignende implementeringer.
Testbarhed: Efter at koden er skrevet, kan 90% af korrektheden automatisk verificeres med det samme.
Vedligeholdelsesvenlighed: Et halvt år senere kan enhver, der ser spec'en, forstå de oprindelige designintentioner.
Lave kommunikationsomkostninger: Under teamdiskussioner diskuteres kun spec'en, ikke specifikke kodelinjer.
Indbygget sikkerhed/kvalitet: Sikkerhedskrav (f.eks. parameteriserede forespørgsler) og grænsetilfælde er specificeret i spec'en, og AI skal overholde dem.

5. Eksempel på en god spec (minimal version)

# Spec: Brugerregistrerings-API

## Omfang
- Accepterer email, password
- Sender ikke bekræftelsesmail, kontrollerer ikke e-mailens ægthed

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

## Adfærd
- email skal overholde RFC 5322 grundlæggende format (a@b.c)
- password: længde 8-20, mindst ét tal og ét stort bogstav
- Brug bcrypt til krypteret lagring, salt-omkostning 10
- Hvis email allerede findes før lagring i databasen → 409

## Testcases (input -> forventet statuskode + svarfelt)
| Input email | password | Forventet |
|------------|----------|----------|
| test@x.com | Pass1234  | 201, user_id eksisterer |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (eksisterende email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Ikke-funktionelle krav
- SQL skal bruge parameteriserede forespørgsler (injektionssikring)
- Logning af registreringskilde IP, ikke adgangskode
- Svartid: 95% af forespørgsler < 100 ms (ekskl. bcrypt)

## Afhængigheder
- Python 3.10+, FastAPI, bcrypt, asyncpg

God Spec-kodning = at skrive menneskets 'designbeslutninger' som maskinens 'testcases + typesignaturer + adfærdsbegrænsninger', så AI kun står for at udfylde implementeringen, mens mennesket altid styrer kvalitet og retning.