Hoe een goed gestructureerd codeerproces met AI-agenten echt werkt

Veel gesprekken over AI-gestuurde codering gebeuren op het niveau van 'feeling'. Iemand zegt dat het model 'nu gewoon code schrijft' en je staat daar op dinsdagmiddag met een deadline en een rommelige codebase en moet het zelf uitvogelen.

Dat gat tussen de demo en de werkelijkheid is waar veel bureaus vastlopen. Ze pakken een coding agent, starten een project, en ontdekken na drie dagen dat ze een stapel netjes uitziende code hebben gemaakt zonder enige coherente structuur eronder. Het model was nuttig. Het proces niet.

Hier volgt hoe wij hierover denken bij Studio Hyra. een fase-per-fase beschrijving van hoe een gedisciplineerde AI-gestuurde coderingspraktijk er werkelijk uitziet, gebaseerd op echt werk voor klanten. Geen tutorial. Meer iets als veldaantekeningen.

Begin met een spec waar het model mee in debat kan gaan

De grootste fout bij AI-gestuurde codering is het model behandelen als een zoekmachine voor syntax. Je typt een vaag idee, het geeft netjes ogende code terug, je plakt het in, herhaal. Dit werkt tot het ineens helemaal misgaat.

De fase die meeste teams overslaan is de specificatie. Voordat je een chat opent heb je een geschreven beschrijving nodig van wat je bouwt, concreet genoeg dat iemand het erover oneens kan zijn. Niet een PRD voor een productmanager. Een technische brief: de datastructuur, de constraint, het edge case dat je al kent, het wat je niet gaat doen.

We schrijven deze in gewone markdown. Een paar honderd woorden is prima. Het doel is het model iets geven waar het tegenin kan gaan. Als we de brief delen en het model vragen gaten aan te wijzen, vindt het vrijwel altijd een of twee. Dat gesprek, voordat een regel code is geschreven, is vaak het waardevoolste deel van de hele sessie.

Werk in kleine, reviewbare stappen

Zodra de spec er is, wil je alles aan het model geven en het laten draaien. Resist dat impulse. De output zal lang zijn, lokaal logisch, en globaal verward. Je besteedt meer tijd aan begrijpen wat het gebouwd heeft dan het bouwde.

De kunst zit in granulariteit. Verdeel het werk in onderdelen klein genoeg dat je de output van elk ervan in minder dan tien minuten kunt lezen en begrijpen. Een functie, een component, een migratie, een testsuite voor één module. Vraag het model dat onderdeel af te maken, en dan klaar.

Review elke stap als collega, niet als gebruiker. Vraag jezelf: lost dit het juiste probleem op, of het probleem zoals ik het beschreven heb? Dat zijn vaak verschillende dingen. Het model doet precies wat je vraagt. Als je vraag iets verkeerd was, zal de code iets verkeerd zijn, en de volgende stap zal die fout vergroten.

We houden een aantekeningen-bestand bij tijdens sessies. Elke stap krijgt één-regels notitie: wat veranderde en waarom. Het klinkt vervelend en kost ongeveer negentig seconden per stap. Als iets drie uur later kapot gaat, is dat aantekeningen-bestand het enige wat de debugging-sessie kort houdt.

Het sessie-grensoverschrijdings-probleem

Context windows zijn nu lang genoeg dat de meeste mensen ophouden met nadenken over sessiegrenze. Dat is een fout.

Elke coderingssessie heeft een vorm. Aan het begin heeft het model je spec, je code, je gesprekshistorie, en een helder beeld van bedoeling. Naarmate de sessie groeit, vervaagt dat beeld. Oude aannames blijven in context. Herziene versies stapelen zich erop. Het model is niet verward, eigenlijk, maar het werkt vanuit een steeds ingewikkelder en gedeeltelijk tegenstrijdig beeld.

We behandelen het einde van een sessie als een keerpunt. Voordat we sluiten, vragen we het model een samenvatting te schrijven van wat gebouwd is, welke keuzes gemaakt zijn, en wat open staat. Dit gaat in een bestand genaamd HANDOFF.md in de projectwortel. De volgende sessie begint met dat bestand te lezen.

De handoff-notitie is ook nuttig voor jezelf. Er is een bepaald soort cognitieve vermoeidheid die voortkomt uit lange agentsessies, waarin je je productief voelt omdat veel gebeurde, maar je bent kwijt waarom de vroege keuzes gemaakt waren. De handoff-notitie is een record van je redenering, niet alleen de output van het model.

Wanneer het model zeker is en fout

Het moeilijkste om in te stellen met elk coderingmodel is het zekerheidssignaal. Het model schrijft met dezelfde toon of het een leerboekoplossing produceert of een verzonnen API die niet bestaat. Er is geen twijfel in de stem.

Dit is geen fout die je met prompts omheen kunt engineeren. Het is een eigenschap van het systeem. De bestrijding is proces, niet prompting.

Twee praktijken helpen. Ten eerste. als het model een bibliotheek, patroon, of derdenintegratie voorstelt die jij zelf niet gebruikt hebt, verifieer het voordat je erop bouwt. Niet de documentatie, het echte gedrag. Schrijf een klein geïsoleerd test. Vijf minuten verificatie kan een dag ontwarren besparen.

Ten tweede. vraag het model om tegen zijn eigen voorstel in te gaan voordat je het accepteert. Zoiets als: 'Wat zijn de voornaamste redenen waarom deze aanpak voor deze context verkeerd zou kunnen zijn?' De antwoorden zijn soms defensief en oppervlakkig. Maar soms oppervlakten het model een echt risico dat het had ondergewaardeerd. Die asymmetrie is de extra prompt waard.

Bureaus die snel voortgaan met deze tools bouwen meestal een speciale review-ronde in aan het einde van elke fase, waarbij iemand die de code niet schreef, het koud leest. Niet per se om bugs te vinden. Om de plekken te vinden waar de code technisch klopt en conceptueel mis. Het model is goed in het eerste. Het heeft hulp nodig bij het tweede.

Wat dit betekent voor hoe je projecten indeelt

AI-gestuurde codering verandert meer de rol dan het personeelsbestand, op korte termijn tenminste.

De persoon die het model stuurt moet technisch onderlegd genoeg zijn om output op logicaniveau te reviewen, niet alleen op visueel niveau. Ze hoeven geen senior engineer te zijn. Maar ze moeten begrijpen wat de code zou moeten doen, en ze moeten opmerken wanneer het iets anders doet.

Wat op bureaus misgaat is dat het model aan iemand wordt gegeven wiens sterkte ergens anders ligt: een designer die een beetje codeert, een PM die technisch nieuwsgierig is. Dit zijn geen slechte mensen. Ze zijn in de verkeerde rol. Het model produceert vloeiende, kapotte code en zij weten het niet totdat een klant ernaar kijkt.

De praktische implicatie. houd een technisch onderbouwd persoon dicht bij elke AI-gestuurde build, zelfs als ze zelf geen code schrijven. Hun taak is niet typen. Hun taak is lezen wat het model produceerde en bepalen of de richting klopte.

Uiteindelijk komt het hele proces erop neer. Het model doet het werk snel. De vakmanschap zit erin het precies te sturen, eerlijk te reviewen, en te weten wanneer je moet stoppen en opnieuw specificeren in plaats van doorgaan. Dat deel is helemaal niet veranderd.