Je genereerde een prachtige service class. Nette code, goede types, correcte naamgeving. Toen probeerde je het te integreren met je bestaande codebase.
Het gebruikte Express-patronen in een FastAPI-project. Het maakte een nieuwe databaseverbinding aan in plaats van je connection pool te gebruiken. Het importeerde een library die je niet eens hebt geïnstalleerd.
Herkenbaar?
Het probleem is niet AI. Het is context.
AI-modellen zijn getraind op miljoenen repositories. Vraag je om een "user service," dan trekt het uit al die repos. Express, Django, Spring Boot, Rails. Zonder je specifieke stack te kennen pakt het het meest voorkomende patroon. Waarschijnlijk niet het jouwe.
Dit is de fout die de meeste developers maken: ze behandelen AI als een zoekmachine die code schrijft. Beschrijf wat je wilt, krijg code terug, kopieer-plak, debug twee uur.
Er is een betere manier.
Architectuurdocumentatie verandert alles
Wat als AI je stack kende vóór het een regel schreef? Wat als het je naamconventies kende, je directorystructuur, je databasepatronen?
Dat kan. Je moet het alleen vertellen. Op papier.
# Architectuur
- Backend: FastAPI + SQLAlchemy 2.0 (async)
- Frontend: React 18 + TypeScript + Vite
- Database: PostgreSQL 15+ met RLS
- Auth: JWT tokens, bcrypt hashing
- Kernpatroon: domain-driven, event-basedVijf regels markdown. Dat is het verschil tussen AI dat Express-middleware genereert in je FastAPI-project en AI dat code genereert die daadwerkelijk past.
Het verschil in de praktijk
Zonder architectuurdocs genereert AI zoiets:
class UserService:
def __init__(self, db, notification_svc, audit_svc,
subscription_svc, scheduling_svc):
# AI genereerde dit. Vijf dependencies, geen event bus,
# directe calls overal. Klassiek.Met een simpele ARCHITECTURE.md die je event-driven patroon documenteert:
class UserService:
def __init__(self, db: AsyncSession, event_bus: EventBus):
# Twee dependencies. Events handelen de rest af.
# AI genereerde dit ook, maar had architectuurdocs.Zelfde AI. Zelfde prompt. Andere context. De tweede versie past in je codebase omdat AI het patroon begreep vóór het code schreef.
Vijf bestanden, 90 minuten, 90% nauwkeurigheid
We hebben het gemeten. Voor we onze conventies documenteerden was AI-code bruikbaar in zo'n 40% van de gevallen. Na het schrijven van vijf markdown-bestanden (ARCHITECTURE.md, DOMAIN_PATTERNS.md, API_CONVENTIONS.md, DATABASE_PATTERNS.md en TESTING_STRATEGY.md) sprong dat naar 90%.
De investering: zo'n 90 minuten. De opbrengst: elke AI-interactie vanaf dat moment.
Waarom prompts dit nooit oplossen
Je zou je hele architectuur in elke prompt kunnen plakken. Sommige developers doen dat. Ze schrijven prompts van 600 woorden die hun stack beschrijven, hun patronen, hun conventies.
Het werkt. Een keer. Dan heb je dezelfde context nodig voor de volgende prompt. En de volgende. En je vergeet een detail en AI gaat weer z'n eigen gang.
Documentatiebestanden lossen dit permanent op. Ze staan in je repo. Elke AI-interactie erft ze. Je schrijft ze een keer en update ze als patronen veranderen.
De echte oplossing
Stop met AI de schuld geven van inconsistente output. Begin het de context te geven die het nodig heeft.
- Documenteer je stack: welk framework, welke ORM, welke patronen
- Documenteer je conventies: directorystructuur, naamgevingsregels, waar business logic leeft
- Documenteer je grenzen: wat AI moet genereren, waar het van af moet blijven
Je AI is niet kapot. Het staat te raden. Geef het de antwoorden en het stopt met gokken.