Hoe ik AI liet stoppen met hallucineren op onze codebase

AI-codingtools falen bij echte productieprojecten. Ze werken goed op nieuwe code. Ze vallen uit elkaar bij oude code met een geschiedenis.

Ons fintech-project heeft drie jaar aan geschiedenis. Het heeft twee React-frontends, een adminpaneel en een FastAPI-backend. De database is complex met veel tabellen en zware joins.

We probeerden AI te gebruiken om sneller te werken. Dat mislukte.

Ik vroeg de AI om een 'contacts'-tabel aan te maken. Het maakte nieuwe kolommen aan voor namen en e-mails. Het besefte niet dat we deze al hadden in onze 'users'-tabel. Het dupliceerde gegevens in plaats van een foreign key te gebruiken.

De AI was niet dom. Het had geen context. Het nam een beslissing op basis van onvolledige informatie.

Ik stopte met vragen hoe ik betere code kon krijgen. Ik begon te vragen welke context de AI nodig heeft om goede beslissingen te nemen.

We bouwden een gestructureerde workflow. AI is slechts zo goed als de context die je biedt. We maakten die context expliciet.

Dit is onze opzet:

  • ADR-directory: We hebben een map aangemaakt voor Architecture Decision Records. Deze bestanden leggen uit waarom we specifieke keuzes maken. Eén bestand vertelt de AI om bestaande tabellen te controleren voordat er nieuwe worden aangemaakt. Het verbiedt het dupliceren van gebruikersgegevens.
  • context.md: Dit bestand legt onze specifieke termen uit. Het vertelt de AI hoe onze unieke woorden zich tot elkaar verhouden.
  • plot.md: Dit biedt een overzichtelijke kaart van het project en hoe de verschillende onderdelen met elkaar verbonden zijn.
  • Verplichte tests: Elke nieuwe API-route vereist testcases.

Dit veranderde alles. Een keer veranderde de AI een gedeelde utility-functie. De wijziging maakte acht andere onderdelen van het systeem kapot. De testsuite merkte dit onmiddellijk op. De AI zag de fout en herstelde zijn eigen fout door een versie te maken die zowel aan de oude als de nieuwe eisen voldeed.

Zonder tests zou die bug de productie hebben bereikt.

Behandel AI als een nieuwe ontwikkelaar. Je geeft een nieuwe medewerker niet de schuld omdat hij je codebase niet kent. Je biedt documentatie en onboarding aan. Dat deden we ook voor de AI.

Onze structuur:

  • docs/context.md: Projecttermen en verbindingen.
  • docs/plot.md: Overzichtelijke kaart van de codebase.
  • docs/adr/: Specifieke regels zoals tabelcreatie en API-structuur.

Drie regels voor je team:

  • Wees specifiek in ADR's. Gebruik duidelijke instructies in plaats van vage adviezen.
  • Maak documentatie leidend. Vertel de AI dat deze regels voorrang hebben.
  • Verander fouten in regels. Elke keer dat de AI faalt, schrijf je een nieuwe ADR.

Dit systeem maakt AI niet perfect. Het maakt AI voorspelbaar. We willen een codebase waarin AI consistent is, zodat het team sneller kan werken.

Bron: https://dev.to/jaskiratanand/how-i-made-ai-stop-hallucinating-on-our-3-year-old-