Een ontwikkelaar heeft een drielaagse codebase-kaart uitgebracht waarmee AI-codeeragenten een besef van context behouden over verschillende sessies heen.

Waarom AI-agenten een kaart nodig hebben

Chatgebaseerde programmeerassistenten bouwen alleen een mentaal model van een repository op zolang het promptvenster open blijft. Wanneer het contextvenster sluit, verdampt het model, waardoor de agent symbolen, imports en bestandrelaties vanaf nul opnieuw moet ontdekken. Dat heen-en-weer verspilt rekenkracht en maakt de agent minder behulpzaam wanneer een ontwikkelaar tussen bestanden schakelt of na een pauze terugkeert naar een project.

De drie lagen die de kaart vormen

  • Structurele laag – een catalogus van symbolen, functieaanroepen en importverklaringen. Het beantwoordt de statische vraag: "wat roept wat aan".
  • Temporele laag – git-afgeleide signalen zoals file churn-percentages en eigendomsgeschiedenissen. Het laat zien welke delen van de code het vaakst veranderen en wie deze meestal aanpast.
  • Gedragslaag – het gebruikspatroon uit de praktijk, geëxtraheerd uit de eigen bewerkings- en navigatiegeschiedenis van een agent. Het onthult welke bestanden daadwerkelijk samen worden geopend tijdens een programmeersessie, waardoor "echte buren" aan het licht komen die statische analyse mist.

De gedragslaag is het belangrijkst, omdat deze weerspiegelt hoe ontwikkelaars (en agenten) echt werken, en niet alleen hoe de code is verbonden.

Twee manieren om de kaart aan de agent te voeden

  1. Ambient Path – een beknopte samenvatting die in elke interactie wordt geïnjecteerd. Het geeft de agent een directe "snapshot" (bijv. "je bent in module X, deze symbolen bevinden zich in de buurt") zonder extra aanroepen.
  2. Deep Path – on-demand querytools die de agent kan aanroepen wanneer er meer details nodig zijn, zoals een lijst met bestanden die vaak samen veranderen of een tijdlijn van recent eigenaarschap.

Door ambient informatie te scheiden van diepe informatie, blijft de routineprompt licht, terwijl er toch diepgang wordt geboden wanneer dat nodig is.

Ontwerpregels om het systeem licht te houden

  • Sla zware language servers over. De kaart vertrouwt op shallow parsing in plaats van volledige type-inferentie. Het doel is niet om volwassen statische analysers te overtreffen, maar om ze aan te vullen met gedragsinzichten.
  • Houd de graaf beperkt tot per project. Het systeem weeft geen globale afhankelijkheidsgraaf over verschillende repositories heen. Deze beperking vermindert het geheugengebruik en versnelt updates.
  • Hergebruik de bestaande geheugenopslag. Logboeken van bestandswijzigingen komen uit het eigen geheugen van de agent met tool-aanroepen, waardoor dubbele opslag wordt voorkomen en de gegevensbron consistent blijft.

De kaart in de praktijk bouwen

  1. Verzamel structurele gegevens met een snelle scan van de bronbestanden, waarbij symbolen en importregels worden geëxtraheerd.
  2. Haal temporele metrieken op uit de git-geschiedenis van de repository, waarbij wordt genoteerd welke bestanden de meeste commits hebben en wie de auteur ervan is.
  3. Verzamel gedragssignalen door de acties van de agent (bestanden openen, bewerken en navigeren) tijdens echte programmeersessies te loggen. Deze logs vormen de basis voor de "co-occurrence"-matrix die gedragsmatige buren definieert.
  4. Vul de Ambient Path met een korte, geordende lijst van de meest relevante symbolen en bestanden voor de huidige taak.
  5. Maak de Deep Path beschikbaar als een set lichtgewicht queryfuncties (bijv. "lijst bestanden op die in recente sessies samen zijn bewerkt").

Snelle hooks leggen elke bewerking vast terwijl deze plaatsvindt; tragere achtergrondprocessen berekenen de churn-statistieken opnieuw. Samen houden ze de kaart actueel zonder de workflow van de ontwikkelaar te vertragen.

Lessen die onderweg zijn geleerd

  • Splits ambient van on-demand. Door de altijd aanwezige samenvatting klein te houden, wordt token-bloat voorkomen, terwijl rijkere queries optioneel blijven.
  • Prioriteer context per taak. Het ordenen van de ambient symbolen op basis van de huidige focus van de bewerking levert nuttigere suggesties op.
  • Ververs agressief maar intelligent. Snelle hooks leggen wijzigingen met een hoge frequentie vast; periodieke scans verwerken wijzigingen met een lage frequentie en verschuivingen in eigenaarschap.
  • Shallow parsing wint op snelheid. Diepe type-analyse voegt latentie toe zonder het gedragsinzicht te leveren dat de kaart zijn voordeel geeft.

Conclusie: Door statische structuur, git-afgeleide geschiedenis en gebruik in de praktijk te combineren in een compact, tweelaags toegangsmodel, kunnen ontwikkelaars AI-codeeragenten een duurzame kaart van de codebase geven. Het klein houden van de altijd aanwezige samenvatting voorkomt token-bloat.