Technical debt voorkomen bij AI-gegenereerde code

AI-tools maken het makkelijk om snel een prototype te bouwen. Je beschrijft een feature, krijgt werkende code terug en gaat door naar het volgende scherm.

Die snelheid is waardevol. De risico’s ontstaan wanneer elke prompt nieuwe code toevoegt zonder vaste structuur, tests of duidelijke keuzes. Dan groeit een prototype in een paar weken uit tot een codebase waar elke wijziging spannend voelt.

Technical debt voorkom je vooral door AI-output te behandelen als een eerste versie. Snel gemaakt, daarna beoordeeld, getest en ingepast in de rest van het systeem.

Begin met een kleine architectuurafspraak

Leg vooraf vast waar belangrijke onderdelen thuishoren:

• routes en pages
• API-handlers
• database-acties
• validatie
• authenticatie en rollen
• gedeelde UI-componenten
• externe services

Deze afspraak hoeft kort te zijn. Een docs/architecture.md van een halve pagina is vaak genoeg. Het doel is dat elke nieuwe AI-prompt weet waar code geplaatst moet worden.

Voorbeeld:

Nieuwe database-writes gaan altijd via src/server/actions. API-routes doen alleen request parsing, auth checks en response formatting.

Zo voorkom je dat dezelfde logica in pages, API-routes en componenten tegelijk terechtkomt.

Prompt per onderdeel, review per flow

Vraag AI om kleine, afgebakende wijzigingen. Een goede opdracht noemt het bestand, de bestaande conventie en het verwachte gedrag.

Sterke prompt:

Voeg server-side validatie toe aan de bestaande checkout action in src/server/actions/checkout.ts. Gebruik dezelfde foutstructuur als createCustomer. Pas alleen de checkout action en de bijbehorende tests aan.

Zwakke prompt:

Maak checkout beter en veiliger.

Na elke wijziging review je de hele flow:

• Waar komt input binnen?
• Waar wordt input gevalideerd?
• Welke gebruiker mag deze actie doen?
• Welke data wordt opgeslagen?
• Wat ziet de gebruiker bij een fout?
• Welke test bewijst dat dit blijft werken?

Deze flow-review haalt meer problemen boven water dan losse bestandsreview.

Laat AI unit-tests schrijven

AI-code zonder tests is een beetje hetzelfde als rijden zonder borden. Hoe weet je zeker dat je de goede kant opgaat?

Begin met tests voor de paden die belangrijke dingen raken, zoals geld of gevoelige data:

• signup en login
• rollen en rechten
• checkout of aanvraagflow
• betalingen en webhooks
• import en export
• database-mutaties
• e-mail of notificaties

Vraag AI eerst om testcases in gewone taal. Daarna pas om code.

Voorbeeld:

Geef 8 testcases voor deze invite-flow. Denk aan verlopen tokens, bestaande gebruikers, verkeerde rollen en dubbele uitnodigingen. Schrijf daarna Vitest-tests voor de 4 belangrijkste cases.

Dit dwingt het model om edge cases te benoemen voordat het implementatiecode schrijft.

Refactor zodra hetzelfde patroon terugkomt

Duplicatie is een van de snelste manieren waarop AI-code vastloopt. Let op signalen zoals:

• drie formulieren met eigen validatielogica
• meerdere API-routes die dezelfde auth check doen
• componenten met bijna dezelfde loading en error states
• databasequeries verspreid over UI-bestanden
• utility-functies met overlappende namen

Pak duplicatie vroeg aan. Wacht vooral bij auth, betalingen, imports en permissies kort met refactoren. Daar wordt latere cleanup snel duur.

Een goede regel: zodra je dezelfde logica voor de derde keer ziet, maak je er een gedeelde functie, action of component van.

Dit is ook het gedeelte waar code-analysis tools heel handig zijn. Je kan dingen meten zoals code-complexiteit, overbodige code, code coverage, etc.

Houd secrets, env vars en deployment buiten de AI-chat

AI-tools mogen helpen met configuratie, deployment scripts en documentatie. Secrets horen daar buiten te blijven.

Werk met placeholders:

• STRIPE_SECRET_KEY
• DATABASE_URL
• SHOPIFY_ADMIN_ACCESS_TOKEN
• SESSION_SECRET

Controleer daarna:

• staan secrets alleen in .env of je hosting provider?
• staat .env in .gitignore?
• draait productie met andere keys dan lokaal?
• is logging vrij van tokens, wachtwoorden en persoonsgegevens?

Je kan tools zoals een secrets manager gebruiken, zodat je hier niet over na hoeft te denken.

Gebruik een vaste done-check voor elke AI-feature

Een feature is pas klaar wanneer deze checks rond zijn:

• de code volgt de bestaande mappenstructuur
• validatie staat aan de serverkant
• auth en rollen zijn expliciet gecontroleerd
• foutmeldingen zijn voorspelbaar
• de belangrijkste flow heeft tests
• duplicate code is opgeruimd
• deploymentvariabelen zijn gedocumenteerd
• de PR of commit beschrijft de keuze die gemaakt is

Deze checklist houdt snelheid bruikbaar.

Plan periodiek een cleanup-moment

Bij agentic development is refactoring een vast onderdeel van bouwen. Plan bijvoorbeeld elke week een korte cleanup-pass:

• verwijder ongebruikte bestanden
• voeg tests toe voor flows die vorige week live gingen
• trek dubbele validatie naar een gedeelde plek
• controleer package updates en kwetsbaarheden
• werk README of architecture notes bij

Een cleanup-pass van twee uur per week voorkomt vaak een 2.0 later.

Wanneer een externe scan zinvol is

Een codebase scan is nuttig wanneer je prototype werkt en je richting lancering gaat. Vooral bij apps met login, klantdata, betalingen, dashboards of externe koppelingen.

Tijdens zo’n scan kijk ik naar auth, database-acties, API-routes, deployment, tests, afhankelijkheden en duplicate code. Je krijgt daarna een concrete volgorde van aanpak.

Bekijk AI code cleanup bij Odeva als je een AI-gebouwde app wilt laten controleren voordat je verder bouwt.