AI-serie intervju 16: Hur borde en bra spec-kodning se ut?

En bra Spec-kodning (specifikationsdriven programmering) handlar om att omvandla "vaga idéer" till "exakta, verifierbara och körbara kontrakt". Det handlar inte bara om att skriva ett dokument, utan att etablera ett entydigt kommunikationsspråk mellan människa och AI (eller mellan människor). Nedan beskriver jag från fyra dimensioner: specifikationens innehållsstruktur, skrivningsprinciper, samarbetsflöde med AI och kvalitetsverifiering – hur en bra spec ser ut.

1. Standardstruktur för specifikationsdokument (med funktionsmodul som exempel)

Avsnitt	Obligatoriskt innehåll	Exempel
1. Mål och omfattning	En mening som beskriver vad som görs, och tydligt vad som inte görs	"Implementera API för användarregistrering, inkluderar inte e-postverifiering"
2. In-/utdatakontrakt	Datastruktur, typer, obligatoriska/valfria fält, exempelvärden	`POST /register` begäran `{email: string, password: string}`, svar `201` eller `400` med felkod
3. Beteende och logik	Affärsregler, gränsvillkor, tillståndsövergångar	"Lösenordslängd 8-20 tecken, minst en siffra; om e-post redan finns returneras `409`"
4. Felhantering	Alla möjliga undantagsscenarier och motsvarande felkoder/meddelanden	"Databasanslutning misslyckas → returnera `503`, exponera inte stacktrace"
5. Icke-funktionella krav	Prestanda (svarstid < 200ms), säkerhet (parametriserade frågor), loggning, observerbarhet	"All SQL måste vara förkompilerad; logga `email` men inte `password`"
6. Testfall (kritiskt)	Minst 3 typiska indata + 2 gräns-/undantagsindata, med förväntad utdata	Se tabell nedan
7. Beroenden och begränsningar	Vilka bibliotek, versioner, miljövariabler	"Python 3.10+, FastAPI, miljövariabel `DB_URL`"

Exempel på testfall (inbäddade i specifikationen)

Scenario	Indata	Förväntad utdata
Normal registrering	email: `a@b.com`, lösenord: `Pass1234`	`201`, returnerar `user_id`
Lösenord för kort	lösenord: `Ab1`	`400`, felkod `WEAK_PASSWORD`
E-post redan existerar	samma email som ovan	`409`, felkod `EMAIL_EXISTS`

En bra spec måste först skriva testfallen, eftersom AI kan generera enhetstester direkt baserat på dem och automatiskt verifiera efter slutförande.

2. Kärnprinciper för att skriva specifikationer (SMART-variant)

Princip	Förklaring	Motexempel
Exakt (Precis)	Använd specifika siffror, typer, booleska villkor; undvik "så mycket som möjligt", "vanligtvis"	❌ "Lösenordet måste vara tillräckligt säkert" → ✅ "Lösenordet måste vara minst 8 tecken, innehålla versal, gemen och siffra"
Verifierbar (Verifierbar)	Varje krav måste kunna bedömas som godkänt/underkänt genom automatiska tester eller manuell kontroll	❌ "Koden måste vara elegant" → ✅ "Funktionens cyklomatiska komplexitet ≤ 10, inga dubblettkodblock"
Entydig (Entydig)	Samma term har samma betydelse i hela texten; vid behov ges en ordlista	❌ "Om användaren inte finns, returnera fel" → ✅ "Användaren finns inte → returnera `404` med `{code: 'USER_NOT_FOUND'}`"
Fullständig (Fullständig)	Täcker lyckosökväg, alla undantagssökvägar, icke-funktionella krav	❌ Endast framgångsscenario → ✅ Inkluderar databas-timeout, otillräckliga behörigheter etc.
Atomär (Atomär)	En spec beskriver endast en oberoende levererbar funktionspunkt (underlättar för AI att slutföra på en gång)	❌ Använd en spec för "hela betalningssystemet" → ✅ Dela upp i "generera betalningsorder", "callback-signaturverifiering", "återbetalning"

3. Spec-kodningsflöde vid samarbete med AI

Människan skriver spec (ovanstående struktur, särskilt testfall och funktionssignaturer).
Mata spec:en på en gång till AI (inte dialogbaserade tillägg, undvik vibe-kontaminering).
AI genererar kod + enhetstester (AI måste följa testfallen i spec:en för att skapa körbara tester).
Kör testerna: om alla godkänns, gå till nästa steg; om inte, modifiera spec:en eller korrigera koden direkt (då kan en mindre loop påbörjas, men ändringar måste dokumenteras).
Manuell granskning: kontrollera om funktioner utanför spec:en har introducerats (scope creep), kontrollera säkerhet/prestanda.
Förankra: Skicka in spec-dokumentet och slutkoden tillsammans i arkivet som permanent dokumentation.

Nyckelpraktik: Specifikation som kod – använd spec.md + test_spec.py, där testfilen direkt kommer från exemplen i spec:en. På så sätt, när koden senare ändras, räcker det att köra testerna för att verifiera om spec:en har brutits.

4. Effekter av en bra spec (kan användas som acceptanskriterier)

Determinism: Samma spec till olika AI (eller olika personer) ger liknande implementationer.
Testbarhet: När koden är skriven kan 90 % av korrektheten omedelbart verifieras automatiskt.
Underhållbarhet: Vem som helst som tittar på spec:en om ett halvår förstår den ursprungliga designavsikten.
Låg kommunikationskostnad: Under teamdiskussioner diskuteras endast spec:en, inte specifika kodrader.
Inbyggd säkerhet/kvalitet: Säkerhetskrav (t.ex. parametriserade frågor) och gränsvillkor skrivs i spec:en och måste följas av AI.

5. Exempel på en bra spec (minimal version)

# Spec: API för användarregistrering

## Omfattning
- Tar emot e-post och lösenord
- Skickar inte verifieringsmail, kontrollerar inte e-postens äkthet

## Kontrakt
POST /register
Content-Type: application/json
Begäran: { "email": string, "password": string }
Svar 201: { "user_id": string }
Svar 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Svar 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Beteende
- E-post måste följa grundläggande RFC 5322-format (a@b.c)
- Lösenord: längd 8-20, minst en siffra och en versal
- Använd bcrypt för krypterad lagring, salt-omkostnad 10
- Om e-post redan finns innan lagring i databas → 409

## Testfall (indata → förväntad statuskod + svarsfält)
| Indata e-post | lösenord | Förväntan |
|---------------|----------|-----------|
| test@x.com | Pass1234 | 201, user_id finns |
| test@x.com | pass | 400, INVALID_PASSWORD |
| bad | Pass1234 | 400, INVALID_EMAIL |
| (redan existerande e-post) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Icke-funktionella krav
- SQL måste använda parametriserade frågor (för att förhindra injektion)
- Logga registreringskällans IP, logga inte lösenord
- Svarstid för 95 % av förfrågningar < 100 ms (exklusive bcrypt)

## Beroenden
- Python 3.10+, FastAPI, bcrypt, asyncpg

Bra spec-kodning = att skriva människans "designbeslut" som maskinens "testfall + typsignaturer + beteendebegränsningar", så att AI endast ansvarar för att fylla i implementationen, medan människan alltid kontrollerar kvaliteten och riktningen.