AI-serie interview 16: Hoe ziet een goede spec-codering eruit?

Een goede Spec Coding (specificatiegedreven programmeren) draait erom "vage ideeën" om te zetten in "precieze, verifieerbare, uitvoerbare contracten". Het is niet alleen het schrijven van een document, maar het opzetten van een ondubbelzinnige communicatietaal tussen mens en AI (of tussen mensen). Hieronder bespreek ik vanuit vier dimensies — inhoudsstructuur van de specificatie, schrijfprincipes, samenwerkingsproces met AI en kwaliteitsvalidatie — hoe een goede specificatie eruitziet.

1. Standaardstructuur van een specificatiedocument (bijvoorbeeld voor een functiemodule)

Hoofdstuk	Verplichte inhoud	Voorbeeld
1. Doel en scope	Één zin die uitlegt wat er wordt gedaan, expliciet wat niet	"Implementeer gebruikersregistratie-API, geen e-mailverificatie"
2. Invoer/uitvoer contract	Gegevenstypen, types, verplichte/optionele velden, voorbeeldwaarden	`POST /register` request body `{email: string, password: string}`, response `201` of `400` met foutcode
3. Gedrag en logica	Bedrijfsregels, randgevallen, toestandsovergangen	"Wachtwoordlengte 8-20 tekens, minimaal één cijfer; bij bestaande e-mail retourneer `409`"
4. Foutafhandeling	Alle mogelijke uitzonderingsscenario's met bijbehorende foutcodes/berichten	"Databaseverbinding mislukt → retourneer `503`, geen stacktrace tonen"
5. Niet-functionele eisen	Prestaties (respons < 200ms), beveiliging (geparametriseerde query's), logging, observeerbaarheid	"Alle SQL moet voorbewerkt zijn; log `email` maar niet `password`"
6. Testgevallen (kritiek)	Minimaal 3 typische inputs + 2 rand/uitzonderlijke inputs, met verwachte output	Zie onderstaande tabel
7. Afhankelijkheden en beperkingen	Welke bibliotheken, versies, omgevingsvariabelen	"Python 3.10+, FastAPI, omgevingsvariabele `DB_URL`"

Voorbeeld testgevallen (ingebed in de specificatie)

Scenario	Invoer	Verwachte output
Normale registratie	email: `a@b.com`, wachtwoord: `Pass1234`	`201`, retourneer `user_id`
Wachtwoord te kort	wachtwoord: `Ab1`	`400`, foutcode `WEAK_PASSWORD`
E-mail bestaat al	zelfde email	`409`, foutcode `EMAIL_EXISTS`

Goede specificaties schrijven eerst testgevallen, omdat AI daarmee direct unittesten kan genereren en automatisch kan valideren na voltooiing.

2. Kernprincipes voor het schrijven van specificaties (SMART-variant)

Principe	Uitleg	Tegenvoorbeeld
Precies (Precise)	Gebruik concrete getallen, types, booleaanse condities; vermijd "zoveel mogelijk", "meestal"	❌ "Wachtwoord moet veilig genoeg zijn" → ✅ "Wachtwoord minimaal 8 tekens, met hoofdletter, kleine letter en cijfer"
Verifieerbaar (Verifiable)	Elke eis kan worden beoordeeld als geslaagd/mislukt via automatische tests of handmatige controle	❌ "Code moet elegant zijn" → ✅ "Functie cyclomatische complexiteit ≤ 10, geen dubbele codeblokken"
Ondubbelzinnig (Unambiguous)	Zelfde term heeft door de hele tekst dezelfde betekenis; indien nodig een verklarende woordenlijst	❌ "Als gebruiker niet bestaat, retourneer fout" → ✅ "Gebruiker bestaat niet → retourneer `404` met `{code: 'USER_NOT_FOUND'}`"
Volledig (Complete)	Dek het gelukspad, alle uitzonderingspaden en niet-functionele eisen af	❌ Alleen succes-scenario's geschreven → ✅ Inclusief database-timeout, onvoldoende rechten, etc.
Atomair (Atomic)	Eén specificatie beschrijft één onafhankelijk leverbare functie (handig voor AI om in één keer af te ronden)	❌ Één specificatie voor "het hele betalingssysteem" → ✅ Opgesplitst in "betaalopdracht genereren", "callback-handtekening verifiëren", "terugbetaling"

3. Spec-coderingsproces bij samenwerking met AI

Mens schrijft specificatie (bovenstaande structuur, vooral testgevallen en functiehandtekeningen).
Voer de specificatie in één keer aan AI (geen dialogische toevoeging van vereisten om vibe-vervuiling te voorkomen).
AI levert code + unittesten (AI moet uitvoerbare tests genereren op basis van de testgevallen in de specificatie).
Voer tests uit: als alle slagen, ga naar volgende stap; indien niet, pas specificatie aan of corrigeer code direct (kleine lus mogelijk, maar wijzigingen vastleggen).
Menselijke beoordeling: controleer op functionaliteit buiten de specificatie (scope creep), beveiliging/prestaties.
Bevriezen: spec-document en uiteindelijke code samen in de repository vastleggen als permanente documentatie.

Kritieke praktijk: Specificatie als code — gebruik spec.md + test_spec.py, waarbij het testbestand direct afkomstig is uit de voorbeelden in de specificatie, zodat bij latere code-wijzigingen alleen de tests gedraaid hoeven worden om te valideren of de specificatie is geschonden.

4. Effecten van een goede specificatie (kan als acceptatiecriteria dienen)

Determinisme: Dezelfde specificatie levert bij verschillende AI's (of mensen) vergelijkbare implementaties op.
Testbaarheid: Na het schrijven van de code kan direct 90% van de juistheid automatisch worden geverifieerd.
Onderhoudbaarheid: Na een half jaar kan iedereen die de specificatie leest de oorspronkelijke ontwerpbedoelingen begrijpen.
Lage communicatiekosten: Teamdiscussies gaan alleen over de specificatie, niet over specifieke coderegels.
Ingebouwde beveiliging/kwaliteit: Beveiligingseisen (zoals geparametriseerde query's) en randgevallen staan in de specificatie; AI moet zich eraan houden.

5. Voorbeeld van een goede specificatie (minimale versie)

# Spec: Gebruikersregistratie-API

## Scope
- Ontvang email, password
- Verstuur geen verificatiemail, controleer geen echte e-mail

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

## Gedrag
- email moet voldoen aan basis RFC 5322-formaat (a@b.c)
- password: lengte 8-20, minimaal één cijfer en één hoofdletter
- Gebruik bcrypt voor versleutelde opslag, salt cost 10
- Indien bij opslaan in database blijkt dat email al bestaat → 409

## Testgevallen (invoer -> verwachte statuscode + responsveld)
| Invoer email | password | Verwachting |
|--------------|----------|-------------|
| test@x.com   | Pass1234 | 201, user_id bestaat |
| test@x.com   | pass     | 400, INVALID_PASSWORD |
| bad          | Pass1234 | 400, INVALID_EMAIL |
| (bestaande email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Niet-functioneel
- SQL moet geparametriseerde query's gebruiken (injectiebestendig)
- Log registratie-bron-IP, log niet het wachtwoord
- Responstijd 95% van verzoeken < 100ms (exclusief bcrypt)

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

Goede Spec Coding = menselijke ontwerpbeslissingen omzetten in machinale testgevallen + typehandtekeningen + gedragsbeperkingen, zodat AI alleen de implementatie invult, terwijl de mens de kwaliteit en richting blijft bewaken.