Maguyva Blog

Context die met je meereist

Mon, 07 Sep 2026 00:00:00 GMT

Cursors indexer is uitstekend binnen Cursor. Tab-aanvulling, inline bewerken, chat, en de agent in dat venster steunen al op een projectindex die Cursor beheert voor de geopende werkruimte. Als Cursor de enige omgeving is waarin je schrijft, en die index vindt al de juiste bestanden, blijf daar. Dat is het eerlijke ‘blijf-waar-je-bent’-geval, en het opent terecht deze pagina.

Dit stuk gaat over de andere helft van een gewone week. Dezelfde repository wordt ook geopend in Claude Code, bevraagd vanuit Codex CLI, beoordeeld op een tweede machine, of bevraagd door een agent die in CI draait. De vraag is niet ‘welke indexer is beter’. De vraag is of de kaart waar de agent in het ene venster op vertrouwt, dezelfde kaart is waar hij in het volgende op vertrouwt.

Maguyva is die kaart die met je meereist. Het is een externe MCP-contextlaag voor de codebase. De agent bevraagt het op dezelfde manier als elk ander MCP-hulpmiddel. Resultaten komen terug als gerangschikte paden met regelnummers. Cursor blijft de editor. De context is wat verplaatst.

Waar Cursors indexer voor dient

Cursors ingebouwde indexering bestaat zodat chat, agent en zoeken binnen de editor relevante code kunnen ophalen in plaats van alleen te vertrouwen op wat past in het ruwe contextvenster van het model. Dat is het juiste ontwerp voor een IDE. Deze index is nativ voor Cursor. Het is geen MCP-server en is vanuit geen enkele andere client bereikbaar.

Zo werkt het, zoals beschreven in Cursors publieke documentatie en Cursors eigen weergave op het moment van schrijven: het belangrijkste zoekpad is niet langer een cloud-embeddingindex. Cursors team heeft op hun communityforum verklaard dat toegewijd semantisch, op embeddings gebaseerd zoeken wordt afgebouwd ten gunste van grep-gebaseerd ophalen, omdat huidige modellen een levende boom al goed genoeg zelf kunnen doorzoeken. In de plaats daarvan staat Instant Grep, een lokale zoekindex opgebouwd uit n-grammen, omgekeerde lijsten en Bloomfilters, bewaard in een in het geheugen gemapte opzoektabel, zodat query’s worden opgelost op de eigen machine van de ontwikkelaar in plaats van op een server.

De index zelf leeft in de eigen .git/cursor/-map van de repository, verankerd aan een specifieke git-commit; wijzigingen sinds die commit stapelen zich erbovenop in plaats van een nieuwe scan te starten, en de index wordt alleen herbouwd wanneer de lokale toestand ver is afgeweken van waarop hij gebouwd was. Omdat hij zich binnen .git bevindt, wordt hij nooit getrackt en nooit gepusht — verwijder de map, en de index is weg. .gitignore wordt gerespecteerd door constructie, aangezien alleen door git getrackte inhoud in aanmerking komt, en .cursorignore wordt afgedwongen op het leespad. Er is op dat pad geen server-side embeddingstap en geen externe vectordatabase meer. Eerdere documentatie beschreef een cloud-ondersteund ontwerp — versleuteling van chunks, synchronisatie via een Merkle-boom, hergebruik van de index tussen teamgenoten — en Cursors eigen team heeft inmiddels gezegd dat dat ontwerp wordt afgebouwd, dus deze tekst beschrijft het niet langer als actueel.

Een opvallend sterk punt binnen de editor is Cursors Explore-subagent. Die kan meerdere parallelle zoekopdrachten starten in zijn eigen contextvenster op een sneller model en alleen de relevante bevindingen teruggeven, zodat het hoofdgesprek niet opzwelt van zoekresultaten. Dat is een echte kracht binnen de editor. Behoud die.

Multi-root werkruimtes worden ondersteund: de context van elke geopende map is beschikbaar voor Agent. Sommige git-afhankelijke functies, zoals worktrees, zijn uitgeschakeld in multi-root-opstellingen, en Cloud Agents ondersteunen multi-root werkruimtes helemaal niet.

Niets daarvan is een reden om Cursor te verlaten. Het is een precieze beschrijving van een kaart die uitstekend is waar hij leeft.

Wat ‘meereizen’ echt betekent

Een kaart reist met je mee wanneer dezelfde vragen hetzelfde soort antwoord opleveren, met citaten die je kunt openen, vanuit meer dan één client.

In Cursor: ‘Waar is parseConfig gedefinieerd, en wie roept het aan?’
In Claude Code, op dezelfde repo: dezelfde vraag.
In Codex CLI, op een reviewmachine die het Cursor-venster nooit heeft geopend: dezelfde vraag.
In een CI-agent die MCP spreekt: dezelfde vraag, tegen dezelfde gehoste snapshot.

Als elke omgeving zijn eigen privé-index bouwt, heb je geen ene kaart. Je hebt meerdere caches die uit elkaar drijven. De editorindex kan actueel zijn voor de boom op schijf. De CLI-sessie kan een dag achterlopen. De CI-taak kan naar een andere checkout kijken. En de agent zal toch zelfverzekerd blijven klinken.

Cursors indexer hoort dat niet op te lossen. Omdat hij binnen de editor leeft, is de context die hij bouwt voor die editor. Een lezer die ook een CLI, een CI-pipeline, of een andere editor nodig heeft, heeft een apart hulpmiddel nodig voor die omgevingen. Dat is een feit over reikwijdte, geen tekortkoming. Maguyva is dat aparte hulpmiddel.

Een gepubliceerd aantal talen voor Cursors indexer wordt niet vermeld in het materiaal dat deze tekst mag gebruiken. Maguyva publiceert ondersteuning voor meer dan 279 talen en tekstgebaseerde technologieën. Cursors prijzen worden hier ook niet overgenomen; zie hun prijspagina. Maguyva rekent per werkruimte, niet per plek, met gepubliceerde plannen van $0, $19, $49 en $149, afhankelijk van de geïndexeerde omvang en de grootte van de werkruimte.

Eén gehoste kaart, elke MCP-client

Maguyva is een externe MCP-server. Je koppelt GitHub, kiest de repositories, en de cloudpipeline bouwt symbolen, grafrandjes en een gerangschikte kaart. Je voegt een API-sleutel toe aan de MCP-configuratie van de client die je al gebruikt. Maguyva heeft installatiegidsen voor 24 gedocumenteerde MCP-clients — inclusief Cursor — en kan verbinding maken met andere MCP-compatibele clients die standaardconfiguratie ondersteunen.

De Cursor-installatiepagina is het editorspecifieke pad als je daar werkt. Dezelfde server beantwoordt Claude Code, VS Code, Windsurf, Codex CLI en de rest. Je wisselt niet van editor. Je geeft elke agent hetzelfde hulpmiddeloppervlak: 11 klantgerichte MCP-hulpmiddelen voor zoeken, symbolen, afhankelijkheidsanalyse, bestandsophaling, repository-context en deterministische hulpwerkstromen. Semantisch, structureel, graaf- en tekstzoeken worden samengevoegd tot gerangschikte resultaten.

Dat is het voordeel van overdraagbaarheid. De citaten die je vanmorgen in Cursor hebt gecontroleerd, hebben dezelfde vorm als de citaten die Codex CLI vanavond teruggeeft. Bestandspad en regelnummer. Open ze. Als ze verkeerd zijn, zie je dat. Als ze kloppen, heeft de volgende wijziging een plek om te landen. De goedgekeurde bewering is minder gehallucineerde wijzigingen, niet de belofte dat elke wijziging correct is.

Versheid is gepubliceerd. Snapshots zijn van een tijdstempel voorzien, zodat de agent weet welke versie van de boom hij leest. De herbouwfrequentie is dagelijks in het gratis plan en elk uur in de betaalde plannen. De eerlijke beperking is niet-gesynchroniseerd lokaal werk: een wijziging die alleen bestaat in een werkboom staat nog niet in de gehoste kaart. Die beperking is hetzelfde ongeacht vanuit welke client je bevraagt, en dat is precies het punt. Drift tussen clients is niet langer een tweede, verborgen beperking.

De documentatie geeft de activeringslus die voor elke client geldt: indexeer een repo die je al kent, verbind de client, stel één vraag die je kunt verifiëren. Doe dat eenmaal in Cursor. Doe het opnieuw vanuit de CLI die je echt gebruikt op reviewdagen. Als beide antwoorden dezelfde handler citeren, is de kaart daadwerkelijk met je meegereisd.

Hoe de twee kaarten naast elkaar bestaan

Gebruik beide. Het zijn geen alternatieven in de zin van een vergelijkingspagina.

Laat Cursors indexer aan staan voor het project op schijf. Laat Explore, Instant Grep en de agent binnen de editor het gebruiken. Die lus is nativ en snel.
Voeg Maguyva toe als MCP-server in Cursor, zodat dezelfde sessie ook de gehoste werkruimtekaart kan bevragen. Cursor is een gedocumenteerde Maguyva-client. Je kiest niet de ene index en wist de andere.
Voeg dezelfde Maguyva-server toe aan Claude Code, Codex CLI, of elke andere MCP-client die de repo raakt. Eén API-sleutelvorm. Eén werkruimte.
Als een CI-agent MCP-compatibel is, wijs hem naar dezelfde server. Hij leest dezelfde tijdgestempelde snapshot die de laptop las.

De editorindex blijft het beste hulpmiddel voor ‘wat staat er nu op schijf in dit venster’. De gehoste kaart is het beste hulpmiddel voor ‘hoe ziet deze werkruimte eruit voor elke agent die hem vandaag raakt’. Die zinnen concurreren niet.

Werkruimtequota worden gepubliceerd op de prijspagina: repo’s, geïndexeerde regels en gebruikers, gefactureerd per werkruimte. Agenten en mensen delen hetzelfde gebruikersaantal. Begin gratis met een repo die je al kunt beoordelen. Verhoog de werkruimte pas nadat de citaten het contact met de boom hebben overleefd.

Wat deze pagina niet beweert

Hij beweert niet dat Cursors indexer zwak, onvolledig, of een reden is om van editor te wisselen. De eerste zin van deze tekst zegt het tegenovergestelde.

Hij beweert niet dat Maguyva Instant Grep of de Explore-subagent vervangt. Dat zijn Cursor-functies. Ze blijven in Cursor.

Hij verzint geen aantal talen, geen latentiecijfer, en geen tokenbesparing voor een van beide producten. Onbekende cijfers blijven ongepubliceerd.

Hij doet niet alsof niet-gepusht lokaal werk in de gehoste kaart staat. Tijdgestempelde snapshots maken die beperking zichtbaar. Ze verwijderen hem niet.

De test is gewoon. Indexeer een repo die je al kent. Stel één vraag die je kunt verifiëren, eerst in Cursor, dan in een tweede MCP-client. Context die met je meereist is hetzelfde citaat op beide plekken.

// same map, wherever you opened it.

Eerst de kaart, dan de review

Mon, 07 Sep 2026 00:00:00 GMT

Twee verschillende taken staan aan weerszijden van een pull request. Voordat de agent schrijft, heeft hij een kaart nodig van de boom die hij op het punt staat te wijzigen. Nadat de agent een PR opent, zou iets die wijziging moeten lezen tegen de rest van het systeem en commentaar moeten achterlaten waarop een mens kan handelen.

Die taken lijken op elkaar van veraf omdat beide ‘de codebase begrijpen’ inhouden. Het is niet hetzelfde product. De ene beantwoordt ‘waar zou deze wijziging moeten landen?’. De andere beantwoordt ‘wat heeft deze diff kapotgemaakt dat een regel-voor-regel linter zal missen?’. Ze door elkaar halen levert een slechter eerste concept en een luidruchtigere review op.

Dit stuk is een gids voor een gezamenlijke workflow. Maguyva is de kaart die de agent eerst bevraagt. Greptile is de reviewagent die de PR daarna becommentarieert. Het duo is complementair door constructie: Maguyva beoordeelt geen pull requests, en Greptile vervangt niet de contextlaag die de agent gebruikte om ze te schrijven.

Waarom deze opsplitsing nuttig is

Een codeeragent die vertrekt vanuit trainingspriors plus een paar geplakte bestanden zal een aannemelijk pad verzinnen en het bewerken. Dat is de mislukking van ‘het verkeerde bestand’, en het is een ophaalprobleem. Maguyva is een externe MCP-contextlaag voor de codebase: semantisch, structureel (AST), graaf-/afhankelijkheids- en tekstueel ophalen samengevoegd tot gerangschikte resultaten, plus symboolzoeken en bestandsophaling. Onderbouwde antwoorden komen terug als path/file.ext:line, zodat je een misser kunt afwijzen voordat er een patch bestaat. De bewering blijft bescheiden: minder gehallucineerde wijzigingen. Het model kan nog steeds gokken. Alleen stopt de eerste stap met gokken zijn.

Greptile is een AI-code-reviewagent. In hun eigen woorden beoordeelt het automatisch elke pull request met volledig begrip van de codebase, en zet dat af tegen traditionele linters die bestanden geïsoleerd controleren in plaats van het hele systeem. De installatie bestaat uit het installeren van de GitHub- of GitLab-app en het selecteren van repositories. Er is geen lokale index die jij moet draaien. De hosting is Greptile Cloud (ze verklaren SOC 2 Type II-naleving, met een rapport beschikbaar op verzoek), met een self-hosted optie aangeboden aan bedrijven.

Hun eigen genummerde flow is: verbinden en een afhankelijkheidsgraaf bouwen van elke functie, klasse en afhankelijkheid; bij elke pull request de wijziging analyseren met die volledige repo-graaf en bevindingen publiceren als PR-commentaar met voorgestelde correcties, in ongeveer drie minuten; elk commentaar kan het probleem doorgeven aan een codeeragent die het team al gebruikt. Ze verklaren ook dat ze in de loop van de tijd eerdere menselijke PR-commentaren lezen, om de codestandaarden van een team te leren en luidruchtige suggesties te verminderen. Hun leersysteem heeft naar eigen zeggen 2-3 weken nodig om zich aan te passen.

Dat is review, geen concept schrijven. Greptiles sterke punt is de context van de volledige repo-graaf op de wijziging die al in een PR is geland, gevolgd door een gesloten lus die de bevinding naar Claude Code, Codex, Conductor, Cursor, of Devin stuurt. Maguyvaas sterke punt is de gerangschikte kaart die de agent bevroeg voordat die wijziging werd geschreven. Gebruik beide. Vraag geen van beide om het werk van de ander te doen.

Een first-party productintegratie tussen Maguyva en Greptile is niet vermeld. Die heb je ook niet nodig. Maguyva praat met de agent via MCP. Greptile praat met GitHub of GitLab via hun eigen app. Ze ontmoeten elkaar bij de pull request. Geen lijmscript, geen cron die het ene hulpmiddel met het andere verbindt. Het duo doet het zonder bash omdat elk product al op het oppervlak zit dat het toebehoort.

Wat dit niet is

Dit is geen sloop van Greptile. Het is geen ‘wissel je reviewer’-pagina. Greptile lanceerde op Hacker News op 5 maart 2024 als een Y Combinator W24-bedrijf, en die thread is hoe veel mensen het product voor het eerst leerden kennen. Als je ze zo hebt gevonden, blijf ze gebruiken. Deze pagina is de ontbrekende voorste helft van die lus: de agent op voorhand verankeren, zodat de PR die Greptile ziet al op de juiste bestanden mikt.

Greptiles marketingmateriaal leidt met beweringen over reviewsnelheid en het vinden van bugs. Behandel die als Greptiles eigen beweringen, niet als onafhankelijk geverifieerde cijfers. Deze tekst herhaalt ze niet als feiten.

Taaldekking is dezelfde soort eerlijkheid. Greptile kadert ondersteuning als dekking van alle programmeertalen in plaats van een opgesomde lijst; een precies aantal wordt niet vermeld. Maguyva publiceert ondersteuning voor meer dan 279 talen en tekstgebaseerde technologieën, met een technische opsplitsing (parser-ondersteunde AST versus alleen tekst) op de site wanneer de vraag technisch is. Dat zijn verschillende producten die verschillende beweringen doen. Meng ze niet.

Greptiles prijzen worden niet vermeld in het materiaal dat deze tekst mag gebruiken. Betaalde plannen bestaan; zie hun prijspagina. Maguyva rekent per werkruimte, niet per plek. Plannen beginnen gratis. De prijspagina somt de gepubliceerde niveaus op als je de werkruimtecijfers nodig hebt.

Workflow

Drie benoemde fasen. Voer ze in deze volgorde uit. Sla er geen over de eerste keer dat je het duo probeert.

1. Maguyva-context

Indexeer één repository die je al kent. Verbind de MCP-client waarin je al schrijft — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, of een andere MCP-compatibele client. Maguyva heeft installatiegidsen voor 24 gedocumenteerde MCP-clients en kan verbinding maken met andere clients die standaard MCP-configuratie ondersteunen.

Stel een vraag die je kunt beoordelen voordat iemand een regel schrijft. ‘Waar wordt het verlopen van de sessie afgehandeld, en wat roept dat aan?’ is een betere eerste zet dan ‘los auth op’. Eis citaten. Open de file.ext:line-resultaten. Volg het symbool. Bevestig de afhankelijkheid die je op het punt staat aan te raken.

Maguyva stelt 11 klantgerichte MCP-hulpmiddelen beschikbaar voor zoeken, symbolen, afhankelijkheidsanalyse, bestandsophaling, repository-context en deterministische hulpwerkstromen. Vier ophaalmodi worden samengevoegd tot gerangschikte resultaten; find_symbol is een apart hulpmiddel als je de naam al kent. De documentatie beschrijft het kortste pad: begin gratis, indexeer een repo die je al kent, verbind de client, stel dan één vraag die je kunt verifiëren.

Snapshots zijn van een tijdstempel voorzien, zodat de agent kan zeggen welke versie van de boom hij leest. De eerlijke beperking is niet-gesynchroniseerd lokaal werk. Als de wijziging alleen bestaat in een werkboom en niet is gepusht, bevat de gehoste kaart hem nog niet. Instructiebestanden (CLAUDE.md, AGENTS.md) horen hier nog steeds thuis, voor conventies en wat niet aangeraakt moet worden. Het zijn geen levende kaart. Gebruik ze voor gedrag. Gebruik Maguyva voor feiten.

Laat de agent geen PR openen voordat de citaten het contact met de repo hebben overleefd. Die poort is het hele punt van deze fase.

2. PR van de agent

Dezelfde agent schrijft nu de wijziging in de client waarvoor je al betaalt. Maguyva is geen editor en geen reviewer. De agent produceert nog steeds de diff. Je opent nog steeds de pull request op GitHub of GitLab zoals je al doet.

Wat anders zou moeten zijn, is het eerste bestand. De PR zou de handler moeten noemen die het gedrag echt implementeert, de aanroeper die zal breken, en de test die zal falen als de wijziging fout is. Als fase 1 is overgeslagen, besteedt fase 3 zijn commentaar aan een wijziging die in het verkeerde package is geland. Greptile kan nog steeds systemische problemen vinden. Het zou daarnaast niet ook moeten moeten herstellen van een gehallucineerd pad.

Houd de PR beperkt. Een onderbouwd eerste bestand is geen vrijbrief om de module te herschrijven. Dit complementaire duo werkt wanneer de agent één taak deed met een kaart, en daarna een reviewer vroeg een andere taak te doen op een afgebakende diff.

3. Greptile-review

Greptile is al met de repository verbonden via de GitHub- of GitLab-app. Op de nieuwe pull request analyseert het de wijziging met de volledige repo-graaf die het heeft gebouwd, en publiceert bevindingen als commentaar met voorgestelde correcties. Hun eigen materiaal plaatst die doorloop op ongeveer drie minuten.

Lees het commentaar zoals je een zorgvuldige teamgenoot zou lezen: open de geciteerde locatie, beslis of de bevinding echt is, handel dan. Waar Greptile ‘Fix with your Agent’ aanbiedt, stuurt het het probleem — bestandspaden, regelnummers, voorgestelde code — naar Claude Code, Codex, Conductor, Cursor, of Devin. ‘Fix All’ stuurt alle problemen van de review tegelijk. Ze leveren ook een Greptile MCP en een Claude Code-plug-in voor die overdracht. Maguyva staat niet op die genoemde doellijst; die afwezigheid is geen probleem. Maguyva heeft zijn werk al gedaan in fase 1. De codeeragent die de PR schreef, is degene die de correctiepayload zou moeten ontvangen.

Verwacht ruis in de eerste 2-3 weken terwijl Greptiles leersysteem zich aanpast aan het commentaar dat je team echt achterlaat. Dat is hun verklaarde tijdlijn, geen gebrek van het duo. Menselijke review blijft in de lus. Greptile is de geautomatiseerde eerste doorloop, niet de mergeknop.

Als een Greptile-commentaar wijst naar een bestand dat de agent in fase 1 nooit heeft bevraagd, is dat een nuttig signaal. Ofwel miste de kaart een aanroeper, ofwel sloeg de agent een citaat over. Corrigeer het concept op basis van het commentaar. Schakel de reviewer niet uit.

Hoe je dit complement eerlijk houdt

Maguyva altijd eerst. Een review van een PR met het verkeerde bestand blijft een review van het verkeerde bestand.
Greptile altijd daarna. Een goed geciteerd concept heeft nog steeds een leesbeurt van de diff nodig op het niveau van het hele systeem.
Vraag Maguyva niet om PR-commentaar te plaatsen. Dat doet het niet.
Vraag Greptile niet om de eerste ophaallaag van de agent te zijn terwijl die nog een pad aan het kiezen is. Dat is niet het werk waarvoor hun GitHub- of GitLab-app is bedraad.
Verzin geen bash-pipeline die ze ‘synchroniseert’. De PR is de interface.
Verifieer beide kanten onafhankelijk. Indexeer een repo die je al kent. Stel één vraag die je kunt verifiëren. Open dan een kleine PR en lees wat Greptile echt becommentarieert.

De lus is gewoon zodra je hem een naam geeft. Eerst de kaart. Dan de PR van de agent. Dan de review. Elk product blijft aan de kant van de pull request waar het goed in is.

// map first. review second. in that order.

Een AI-agent context geven van een grote repo zonder lokale indexer

Fri, 14 Aug 2026 00:00:00 GMT

Een grote repository past niet in een contextvenster, en als je ooit een laptopindexer op een echte monorepo hebt losgelaten, weet je dat hij daar ook niet comfortabel past — het RAM-gebruik schiet omhoog, de eerste indexering duurt een uur, en je agent begint de volgende sessie nog steeds met gokken welke bestanden ertoe doen.

Het gebruikelijke antwoord is een indexer naast de editor te draaien, en voor een repo die comfortabel op één machine past, is dat een goed antwoord. Als jouw monorepo al snel indexeert in Cursor en dat de enige plek is waar je de kaart nodig hebt, heeft dit stuk niets toe te voegen — sla het over.

Dit stuk gaat over het andere geval — wanneer een agent een doorzoekbare kaart van een grote repo nodig heeft, en jij daarvoor geen lokale indexer wilt draaien.

Wanneer een lokale indexer het verkeerde hulpmiddel is

Een lokale index gaat ervan uit dat de code leeft op de machine die hem bevraagt, en op de schaal van een echte monorepo raakt die aanname zelfs binnen één editor onder spanning. De repo is simpelweg groter dan je ‘warm’ wilt houden op een laptop: je werkt in één package terwijl de impactradius drie mappen verderop ligt, en een eerste koude indexering van een boom van twee miljoen regels is niet iets wat je twee keer wilt doorstaan — niet op je eigen machine, niet op een CI-runner die die boom nog nooit eerder heeft gekloond. Of een teamgenoot zou dezelfde kaart als jij moeten kunnen bevragen, zonder te wachten tot zijn eigen machine zich door dezelfde index heeft geworsteld.

Niets daarvan is een reden om een goede editorindexer weg te gooien. Het is een reden om daarnaast ook een gehoste kaart te hebben die elk van je agenten via MCP kan bevragen.

En het schaalprobleem gaat dieper dan ‘te veel bestanden om te plakken’. Op een grote boom is de interessante vraag bijna nooit ‘laat me dit bestand zien’ — het is welk bestand, welk symbool, welke aanroepers, welke tests. Een agent die begint met het opsommen van src/ en de eerste drie resultaten lezen, mist vrolijk de handler in apps/api en de gegenereerde client in packages/sdk. Wat je nodig hebt, is ophalen dat gebouwd is vanuit de hele boom, dan gerangschikt, dan geciteerd.

Wat ‘context van een grote repo’ echt betekent

Bestanden in de prompt dumpen is geen context — het is een kleinere, slechtere kopie van de boom. Wat je agent echt nodig heeft, is vragen stellen en geciteerde antwoorden terugkrijgen: waar dit symbool is gedefinieerd en wie het aanroept, wat afhangt van de module die ik op het punt sta te wijzigen, welk testbestand dit gedrag dekt, en hoe de boom er nu uitziet, niet vorig kwartaal.

Die antwoorden moeten komen uit een index die van jouw repo is opgebouwd, niet uit het geheugen van het model over andermans repo’s, en de index moet ergens buiten het contextvenster van de agent leven. Voor dit probleem zou hij ook ergens buiten je laptop moeten leven.

Nog iets wat instructiebestanden niet voor je kunnen doen: CLAUDE.md en AGENTS.md zijn de juiste plek voor conventies en gedrag, maar het zijn geen levende, gerangschikte, doorzoekbare kaart van een boom van twee miljoen regels. Gebruik regels voor gedrag; gebruik repo-intelligentie voor feiten.

We bouwen de kaart in de cloud, we bevragen hem vanuit elke client

Maguyva is een externe MCP-contextlaag voor de codebase. Je koppelt GitHub, kiest je repositories, en je kunt weglopen terwijl cloudpipelines de boom parsen, symbolen en grafrandjes bouwen, en een gerangschikte kaart onderhouden — nooit een lokale indexer.

Als je code pusht, worden gewijzigde bestanden incrementeel geparsed, en herbouwen de graaf- en rankinglagen zich volgens een schema: dagelijks in het gratis plan, elk uur in de betaalde plannen. Elke snapshot is van een tijdstempel voorzien, zodat je agent kan zeggen welke versie van de boom hij leest. De eerlijke beperking hier is niet-gesynchroniseerd lokaal werk — een wijziging die alleen bestaat in je werkboom, nooit gepusht, staat nog niet in de gehoste kaart.

Daarna verbind je welke client je ook al gebruikt door een API-sleutel toe te voegen aan diens MCP-configuratie. Er zijn installatiegidsen voor 24 gedocumenteerde MCP-clients, en elke andere MCP-compatibele client die standaardconfiguratie ondersteunt, kan ook verbinding maken. Als Cursor je thuisbasis is, doorloopt de Cursor-pagina dat pad; dezelfde server beantwoordt Claude Code, VS Code, Windsurf, Codex CLI en de rest.

Je wisselt niet van editor. Je geeft je agent een hulpmiddeloppervlak — 11 MCP-hulpmiddelen voor zoeken, symbolen, afhankelijkheidsanalyse, bestandsophaling en repository-context — met dekking van meer dan 279 talen en tekstgebaseerde technologieën, wat meer betekent dan je zou denken op een monorepo die jaren geleden al is opgehouden één taal te zijn.

Antwoorden komen onderbouwd terug, als bestandspaden met regelnummers. Semantisch, structureel, graaf- en tekstzoeken worden samengevoegd tot gerangschikte resultaten, zodat een vraag als ‘wat hangt af van parseConfig’ je geen grep-dump of één semantisch fragment geeft, maar de handvol plekken die er echt toe doen.

Een concrete aanpak

Begin niet met het indexeren van het hele bedrijf. Hier is het pad dat werkt:

Kies één repository die je al goed kent — een package die je handmatig kunt beoordelen is meer waard dan de grootste boom die je hebt.
Begin gratis: 3 repo’s, 50k geïndexeerde regels, alle 11 hulpmiddelen, geen maandelijkse queryquota. Als jouw representatieve repo groter is, somt de prijspagina de werkruimteniveaus op ($0, $19, $49, $149) naar geïndexeerde omvang — niet naar aantal plekken.
Verbind GitHub en wacht tot de eerste indexering klaar is. Je compileert niets lokaal.
Verbind de MCP-client — een paar regels configuratie. Maguyva is een externe MCP-server, dus er zijn geen plug-ins, geen extensies, en geen tweede editor om over te nemen.
Stel één vraag die je kunt verifiëren. ‘Wat hangt af van parseConfig?’ of ‘Waar wordt het verlopen van de loginsessie afgehandeld?’ Open dan de geciteerde file.ext:line-resultaten en controleer ze tegen de boom voor je.
Pas nadat de citaten dat contact hebben overleefd, laat je de agent bewerken.

Als de eerste repo goed past en je boom is groot, verhoog dan de werkruimte om overeen te komen met je geïndexeerde regels en herbouwfrequentie. Mensen en agenten delen hetzelfde gebruikersaantal — Maguyva rekent per werkruimte, niet per plek — dus een derde agent toevoegen aan de lus kost je niets.

De activeringstest is dezelfde die de documentatie aanbeveelt voor elke eerste run: indexeer een repo die je al kent, stel één vraag die je kunt verifiëren. Een grote repo verandert de test niet; hij maakt alleen een verkeerd eerste bestand duurder.

Waar je op moet letten na het verbinden

Houd drie dingen in de gaten. Versheid: betaalde plannen herbouwen elk uur, gratis plannen dagelijks, en niet-gepusht lokaal werk staat niet in de kaart — dat is de afweging die je maakt. Omvang: indexeer een representatieve set repo’s, niet elke gearchiveerde fork; het gratis niveau is bewust zo groot dat je kunt uitzoeken of de antwoorden het waard zijn om te behouden. En verificatie: een kaart van een grote repo die geen paden en regelnummers kan citeren, is gewoon een tragere gokmachine, dus laat je agent de locatie tonen voordat hij de patch aflevert.

Voer dan dezelfde test uit die je op een kleine repo zou uitvoeren. Indexeer een repo die je al kent. Stel één vraag die je kunt verifiëren. Als de kaart echt is, stopt je agent met beginnen vanaf een koude boom.

// no laptop got hot building this map.

Waarom je AI-codeeragent bestandspaden hallucineert

Fri, 14 Aug 2026 00:00:00 GMT

Het teken is geen verkeerde functie-inhoud. Het is een zelfverzekerde wijziging aan een bestand dat niet bestaat, of aan een bestand dat wel bestaat maar niet het bestand is dat het gedrag implementeert.

Je vroeg om een fix voor het verlopen van de sessie. De agent opende src/auth/session.ts. Dat pad is aannemelijk. Het is ook fout. De echte handler leeft in apps/api/src/middleware/expiry.ts, twee refactors geleden hernoemd. De agent loog niet tegen je. Hij vulde een string in de vorm van een pad aan op basis van trainingspriors plus wat al in het contextvenster stond.

Dit is het gebruikelijke faalpatroon op een echte repository. Het model kan code schrijven. De misser zit in het kiezen van de verkeerde plek om het te schrijven.

Waarom agenten paden verzinnen

Een codeeragent is een model dat het volgende token voorspelt, met hulpmiddelen. Als je zegt ‘los het verlopen van de sessie op’, moet hij eerst een bestand noemen voordat hij iets kan lezen of patchen. Als hij nog geen verankerde kaart heeft, construeert hij een pad uit:

Naamgevingsconventies die hij in andere repositories heeft gezien. src/auth/session.ts is een veelvoorkomende vorm.
Bestanden die al in het gesprek staan, die misschien de bestanden zijn die je vorige week hebt geplakt, niet de bestanden die nu ertoe doen.
Mapoverzichten die hij toevallig heeft uitgevoerd, onvolledig op een grote boom.
Instructiebestanden. CLAUDE.md en AGENTS.md vertellen de agent hoe hij zich moet gedragen. Ze zijn geen levende index van symbolen, aanroepers, of huidige paden.

Geen van deze bronnen is vandaag een kaart van deze repository. Het model vult de leemte op dezelfde manier waarop het elke leemte vult: met een vervolg met hoge waarschijnlijkheid. Dat vervolg ziet er vaak uit als een echt pad. Soms bestaat het bestand en ligt het naast het juiste. Soms bestond het op een branch die vorige maand is gemerged. Soms heeft het nooit bestaan.

Grep redt je hier niet als de agent nooit naar de juiste string zoekt. De agent gokte een pad, las vervolgens wat dat pad teruggaf, en bewerkte het toen. De eerste verkeerde stap was het pad, niet de patch.

Bestanden lezen is ook niet hetzelfde als de juiste vinden. Claude Code, Cursor, Codex, en soortgelijke hulpmiddelen kunnen openen waar je ze ook naar wijst. De vraag is of ze betrouwbaar de juiste bestanden vinden, de belangrijke symbolen, de afhankelijkheden, de tests, en de impactradius voordat ze bewerken. Bestandstoegang zonder kaart begint nog steeds met een gok.

De wijziging van het verkeerde bestand is een ophaalprobleem

Behandel het verzonnen pad als een ophaalmisser, niet als een karaktergebrek.

Als de agent path/file.ext:line zou moeten teruggeven voordat hij mag bewerken, zouden er twee dingen gebeuren. Ten eerste zou je het citaat kunnen openen en het werk binnen tien seconden kunnen afwijzen. Ten tweede zou de agent iets moeten bevragen dat de boom echt kent.

Dat is het werk van een codebase-contextlaag. Alleen semantisch zoeken is niet genoeg. Een fragment dat ‘klinkt als het verlopen van de sessie’ kan nog steeds landen in een verouderd package. Je hebt ook exacte tekst nodig als je de string kent, symboolzoeken als je de naam kent, structureel zoeken als je de vorm kent, en een afhankelijkheidsgraaf als je aanroepers en impactradius nodig hebt.

Maguyva is die laag voor MCP-compatibele codeeragenten. Het is geen editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, en andere MCP-clients blijven waar ze zijn. De agent bevraagt een gerangschikte kaart voordat hij een regel aanraakt.

De bewering is bewust bescheiden: minder gehallucineerde wijzigingen. Maguyva ontneemt het model niet het vermogen om te gokken. Het verandert de standaard eerste stap van ‘verzin een aannemelijk pad’ naar ‘vraag om gerangschikte, geciteerde locaties’.

Hoe een onderbouwd antwoord eruitziet

Een nuttig antwoord op ‘waar wordt het verlopen van de sessie afgehandeld’ is geen alinea. Het is een korte lijst van locaties:

apps/api/src/middleware/expiry.ts:48 - de handler
apps/web/src/lib/auth-client.ts:112 - de aanroeper
apps/api/tests/expiry.test.ts:20 - de test die zal falen als de wijziging fout is

Je kunt deze regels openen. Als ze fout zijn, stop je. Als ze kloppen, mag de agent bewerken. De verificatie is het punt, geen slogan.

Maguyva stelt 11 klantgerichte MCP-hulpmiddelen beschikbaar voor zoeken, symbolen, afhankelijkheidsanalyse, bestandsophaling, repository-context en deterministische hulpwerkstromen. Vier ophaalmodi (semantisch, structureel, graaf/afhankelijkheid en tekstueel) worden samengevoegd tot gerangschikte resultaten; symboolzoeken is een apart MCP-hulpmiddel (find_symbol). Onderbouwde antwoorden komen terug met bestandspaden en regelnummers, zodat je ze kunt beoordelen tegen de boom voor je.

De documentatie beschrijft het kortste pad: begin gratis, indexeer een repo die je al kent, verbind de client, stel dan één vraag die je kunt verifiëren.

Een lus die de eerste wijziging verandert

Je hebt geen nieuwe workflowreligie nodig. Je hebt één extra stap nodig voor de eerste keer schrijven.

Stel een vraag die je al kunt beoordelen. ‘Welke code behandelt inloggen en het verlopen van de sessie?’ is beter dan ‘los auth op’.
Eis citaten. Bestandspad en regelnummer, geen samenvatting van ‘de auth-module’.
Open de geciteerde bestanden. Volg het symbool. Bevestig de afhankelijkheid die je op het punt staat aan te raken.
Pas dan laat je de agent patchen.

Als stap 2 niets nuttigs teruggeeft, heeft de agent niet het recht om een pad te improviseren. Hij zoekt opnieuw, of jij wijst het aan. Precies die ene poort levert minder gehallucineerde wijzigingen op. Het model is hetzelfde model. De kaart is wat is veranderd.

Instructiebestanden blijven belangrijk. Behoud ze. Gebruik ze voor conventies, reviewregels, en wat niet aangeraakt moet worden. Vraag ze niet om de index te zijn. Een CLAUDE.md die drie belangrijke mappen opsomt, is verouderd de week na een package-splitsing. Een doorzoekbare kaart wordt bijgewerkt wanneer de repo wordt bijgewerkt.

Een verwante mislukking is het bijna-juiste bestand: de agent opent auth.ts terwijl het gedrag in auth-client.ts leeft, of patcht een gegenereerd bestand in plaats van de bron, of bewerkt de kopie in packages/legacy omdat de naam overeenkwam. Citaten maken deze fouten niet onmogelijk. Ze maken ze zichtbaar voordat de diff landt.

Wat een kaart niet voor je oplost

Wees helder over wat je krijgt. Een onderbouwde kaart maakt niet elke wijziging correct — je agent kan nog steeds een slechte patch schrijven in precies het juiste bestand. Als jouw codebase leunt op dynamische dispatch, reflectie, of monkey-patching, komen sommige symboolzoekopdrachten dunner terug dan je zou willen, omdat dat is wat runtime-indirectie doet met elke statische index. En als je hoopt op een percentage — ‘gehallucineerde paden met X% verminderd’ — vind je dat hier niet, omdat niemand behalve jij dat cijfer eerlijk kan meten voor jouw repo.

Wat je kunt verwachten is smaller en nuttiger: de agent stopt met zijn wijzigingen te openen met een geraden pad. Die eerste stap wordt verankerd in een echte kaart, en daar komen minder gehallucineerde wijzigingen vandaan. Alles na het citaat — de diff lezen, de patch beoordelen — blijft nog steeds jouw werk, net als altijd.

De test kost je bijna niets: indexeer een repo die je al kent en stel één vraag die je kunt verifiëren. Begin met een pad waar je eerder door bent gebrand. Als de citaten fout zijn, zie je dat meteen. Als ze kloppen, heeft de volgende wijziging van je agent een betere plek om te landen.

// it doesn't know the file. it knows how to find it.

Waarom we code search hebben geüpgraded naar voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Benchmarkcijfers in deze post weerspiegelen de RTEB-leaderboards op het moment van publicatie (juni 2026). Leaderboards veranderen; behandel de ranglijsten als een momentopname, geen permanent feit.

Semantisch zoeken is slechts zo goed als de embeddings eronder.

Wanneer een agent Maguyva vraagt “waar handelen we retries af”, grept hij niet naar het woord “retry”. Hij vraagt naar de betekenis — de backoff-lus, de circuit breaker, het ding dat een onbetrouwbare call omhult. Die vraag wordt beantwoord door een vectormodel dat code omzet in een punt in de ruimte en de buren vindt. Kies een beter model en elke semantische query in het product wordt in stilte scherper.

Dus veranderden we het onze. Sinds juni 2026 draaien de code-embeddings van Maguyva op voyage-4-large, ter vervanging van voyage-code-3.

De benchmark

We hebben deze beslissing niet op gevoel genomen. De publieke Retrieval Embedding Benchmark (RTEB) rangschikt embeddingmodellen op echte retrievaltaken, en op het Code-leaderboard staat voyage-4-large op #1 overall (90,86) — vóór gemini-embedding-2-preview (90,26) en, opvallend genoeg, vóór het model dat we al gebruikten, voyage-code-3 (89,73, #3).

Dat is een klein absoluut verschil. Maar het is een verschil in de juiste richting, op een publieke benchmark, op precies de taak waar het ons om gaat: code ophalen op betekenis.

De afweging die we accepteren: binary quantization

Dit is het deel dat de meeste “we hebben ons model geüpgraded”-posts weglaten.

Maguyva slaat geen full-precision vectoren op. We slaan binary-quantized embeddings op: elke 2048-dimensionale vector wordt gereduceerd tot een 2048-bit-signature — 256 bytes per vector. Die signatures worden doorzocht met Hamming-afstand, geïndexeerd en gepartitioneerd per tenant.

Dat is een bewuste afweging. Binary quantization levert wat retrievalprecisie in, in ruil voor drastisch kleinere opslag en snelle, goedkope afstandsberekeningen zonder een aparte vectordatabase om te beheren. Voor een product dat hele repositories per workspace indexeert, weegt die economie zwaarder dan de laatste fractie van een benchmarkpunt eruit persen.

voyage-4-large past in dit ontwerp zonder een migratie van de opslaglaag te forceren: het produceert 2048-dimensionale output, net als voyage-code-3, dus onze bit(2048)-kolommen en Hamming-zoekpad zijn niet veranderd. Het model werd beter; het schema bleef staan.

Code was slechts het begin

Maguyva is een code-intelligentietool. Maar we zijn ook onze eigen eerste klant, en we richten het ook op iets anders: de markdown die in onze repo’s naast de code leeft. Architecture decision records, runbooks, contracten, finance- en policydocumenten — allemaal onder versiebeheer in Git, allemaal achter dezelfde MCP-server, een semantische index over de documenten, niet alleen de bron.

Dat is precies waarom de breedte van voyage-4-large ertoe doet. Op dezelfde familie van RTEB-leaderboards staat het #1 op finance, #1 op healthcare, en #1 op overall text retrieval — vóór Google’s Gemini Embedding, Cohere’s Embed v4, en OpenAI’s text-embedding-3-large. (Voyage is een medeontwikkelaar van RTEB, dus we lezen het als een sterk publiek signaal in plaats van een volstrekt neutrale scheidsrechter — maar het wordt kop-aan-kop gebenchmarkt tegen elk groot commercieel model, op private hold-out-sets.) Dezelfde index die de juiste functie vindt voor een agent, vindt de juiste clausule in een contract of de juiste regel in een policy — en op die domeinen is voyage-4-large geen compromis, het is de koploper.

Waarom we betalen voor premium embeddings

Er is een goedkopere manier om te zoeken, en veel daarvan is gratis. Lexicaal zoeken — BM25 en zijn verwanten — matcht keywords, draait lokaal, en kost niets. Open-source-embeddingmodellen zoals BGE, Nomic en embeddinggemma leveren écht behoorlijke semantische retrieval, en je kunt ze self-hosten voor de prijs van een GPU. Maguyva gebruikt de gratis kant ook: elke query voegt tekst-, AST-, graaf- en semantisch zoeken samen. Waar we niet op beknibbelen, is de semantische laag.

We betalen per token voor premium embeddings — voyage-4-large — in plaats van een gratis model zelf te hosten, om twee redenen. Ten eerste kan keywordzoeken alleen niet antwoorden op “waar handelen we retries af” wanneer de code backoff en circuit breaker zegt en nooit het woord “retry” gebruikt — betekenis is het hele punt van de embedding, en op de domeinen die we bedienen lopen de open modellen achter op de premium modellen: een paar punten achter op algemene tekst, en verder achter in niches zoals code, contracten en finance. Ten tweede bepaalt retrievalkwaliteit in onze ervaring het uiteindelijke antwoord meer dan het model aan de andere kant — een sterke agent die de verkeerde context krijgt, antwoordt nog altijd fout, en hij ziet nooit het document dat hem nooit werd gegeven.

Premium embeddings zijn dus een per-token-rekening die meeschaalt met elke repo en elk document dat we indexeren — en we betalen die met opzet. Voor het resultaat dat onze gebruikers krijgen, de juiste functie of de juiste clausule, denken we dat die afweging het waard is.

Het eerlijke deel

Voyage’s eigen documentatie noemt voyage-code-3 nog altijd het code-geoptimaliseerde model. Waarom dan overstappen?

Omdat we de publieke benchmark lezen, niet alleen de modeltabel van de vendor, en de benchmark zette voyage-4-large bovenaan voor code-retrieval. Dit was een toekomstgerichte beslissing: het nieuwere, over het algemeen sterkere model nemen en het valideren tegen een publiek leaderboard op de taken die ertoe doen. We voelen ons comfortabel bij die weddenschap omdat het bewijs breed is — voyage-4-large wint niet alleen op code, het leidt ook op finance, healthcare en overall retrieval.

Het onopvallende fundament

Elke tool die we blootstellen — semantisch zoeken, task-context gathering, onderbouwde Q&A — komt uiteindelijk neer op retrieval. Wanneer de retriever verbetert, krijgt de agent aan de andere kant beter bewijs, maakt hij minder verkeerde afslagen, en verankert hij zijn antwoorden in de juiste code — of de juiste clausule, of de juiste policy. Een scherper embeddingmodel is geen opzichtige feature. Het is het fundament onder al het andere, en dat hebben we net versterkt. Je zult het niet merken. Dat is precies het punt.

Recursieve zelfverbetering voor talen: code-intelligentie aanscherpen voor ~280 talen

Tue, 26 May 2026 00:00:00 GMT

Cijfers in deze post weerspiegelen het systeem op het moment van publicatie (mei 2026). Zie onze teampagina voor actuele cijfers.

Maguyva extraheert symbolen, referenties en een afhankelijkheidsgraaf uit broncode in ruwweg 280 talen. Elke taal heeft een eigen tree-sitter-handler — queries, heuristieken, edge cases — en elke handler kan op zijn eigen subtiele manier fout zitten. Een method-call die als een read wordt uitgezonden. Een functie toegeschreven aan de verkeerde omsluitende scope. Een relatie die er simpelweg niet is.

Dat kun je niet handmatig auditen. Geen team kan extractie-output over 280 grammatica’s lezen en de slechte edges eruit pikken. De interessante vraag is dus niet “klopt onze extractie” — het is “hoe ontdek je dat die fout is, op deze schaal, zonder dat er bij elke lus een mens aan te pas komt.” Ons antwoord is recursieve zelfverbetering voor talen: een kwaliteitslus aangedreven door taalagents, een LLM die als rechter optreedt, en één regel die we steeds opnieuw leren: groen is niet hetzelfde als correct.

Groen is niet correct

Elke taal heeft een fixture suite, en een releasegate scoort die op vijf dimensies — accuratesse, structurele integriteit, volledigheid, kwaliteit en performance. Een taal wordt pas GREEN wanneer, op zijn fixtures, precisie ≥ 0,95, recall ≥ 0,99 en F1 ≥ 0,97 is, met minstens 20 verwachte edges voor statistische betrouwbaarheid. Daaronder is het YELLOW of RED, en wordt het niet uitgeleverd.

Die gate is noodzakelijk maar niet voldoende. Fixturetests toetsen alleen de gevallen die wijzelf hebben geschreven. Ze leggen de gevallen vast waar we al aan hadden gedacht. Een handler kan foutloos zijn op zijn fixtures en toch een patroon verminken dat alleen in echte code voorkomt — een macro-idioom, een generic-bound method, een taalkenmerk waar niemand een fixture voor heeft geschreven. GREEN betekent dat de fixtures slagen. Het betekent niet dat een echte repository netjes extraheert. Dus moet de lus de fixtures achter zich laten en echte code onderzoeken.

De binnenste lus: steekproef, beoordelen, repareren, bewijzen

De kernlus draait één taal per keer:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Een paar dingen zorgen ervoor dat dit werkt in plaats van zinloos ronddraait.

De rechter is de agent, niet een API-call. Met “LLM-as-judge” bedoelen we dat de taalagent zelf elke gesamplede edge naast de echte bron leest en die classificeert volgens een vaste vijfcategorierubriek: is deze edge correct, een fout-positief, de juiste relatie met het verkeerde type, gekoppeld aan de verkeerde scope, of met verkeerde metadata? Die beoordelingscriteria zijn doorslaggevend — “23% foutpercentage” betekent niets totdat je weet of dat echte defecten zijn of dat de rechter verkeerd telt.

Repareer één ding, en bewijs het dan. Elke iteratie wijzigt precies één bewerkbaar onderdeel, draait dan opnieuw tegen een vaste harness, en behoudt de wijziging alleen als F1 verbetert en de herclassificatie er beter uitziet. Zo niet, dan wordt hij teruggedraaid. Geen batch aan speculatieve edits, geen “zou beter moeten zijn”. Een wijziging verdient zijn plek of verdwijnt. En wanneer een fix beklijft, wordt die gepromoveerd naar de fixture suite — zodat de bug die hij verhielp nooit stilzwijgend kan terugkeren. Die promotiestap is wat de lus recursief maakt in plaats van louter herhalend: elke doorgang versterkt het toetsingskader waar de volgende doorgang op voortbouwt.

De les die we steeds opnieuw leren: metrieken overrapporteren

Dit is de valkuil, en we liepen er recht in. De secundaire corpusmetrieken — hoe vaak een geëxtraheerd target geen oplosbaar symbool heeft, hoeveel symbolen er “verweesd” uitzien, enzovoort — overschatten het aantal problemen enorm. Het zijn meestal paradigma-artefacten, geen bugs.

Het duidelijkste voorbeeld: llvm vertoonde ooit een “source-zonder-symbool”-percentage van 73% en werd als catastrofaal bestempeld. We doken erin. De werkelijke accuratesse was 98,5%. De “ontbrekende symbolen” waren bijna allemaal legitieme externe referenties — calls naar de standaardbibliotheek, naar frameworks, naar code die buiten de repo leeft. De metriek mat een eigenschap van de taal, geen defect in de handler. Talen zoals Zig, COBOL en Odin vertonen “orphan”-percentages van 65–70% en zijn volkomen correct; COBOL had nul echte fouten.

Als we die cijfers het werk hadden laten sturen, hadden we weken besteed aan het “repareren” van handlers die al klopten, terwijl we de talen met stille, echte bugs negeerden. De conclusie is bot: de geaggregeerde metrieken zijn hoogstens een ruw triagesignaal. Het echte kwaliteitssignaal is de steekproef met edge-classificatie — kijken naar daadwerkelijke edges in daadwerkelijke repositories en ze één voor één beoordelen. Data boven intuïtie, maar alleen zodra je weet welke data de waarheid vertelt.

De buitenste lus: een vloot, geen marathon

Eén taal per keer zou eeuwig duren over 280 talen, dus wordt de binnenste lus omhuld door een buitenste die er veel parallel draait.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Elke agent werkt in een wegwerp-worktree, zodat ze elkaar niet voor de voeten lopen. De orchestrator integreert hun fixes één voor één, elk achter een full-manifest-regressiecheck: een wijziging die zijn eigen taal helpt maar stilzwijgend drie andere breekt, landt niet. Integratie wordt bewaakt en bevestigd voordat er iets wordt gepusht — de regressiegate bepaalt wat veilig is, een mens beslist nog altijd wat wordt uitgeleverd. Vervolgens roteert de pool naar de volgende set talen en draait het geheel opnieuw.

Wat nog altijd niet perfect is

De rechter kan het mis hebben, en die fout heeft een richting: een agent die met te weinig context draait overrapporteert. In één batch werden acht talen gemarkeerd met 5–20% fouten; bij inspectie bleek er maar één echte taalspecifieke bug te zijn — de rest waren beoordelingsfouten doordat de eigen semantiek van de taal werd gemist (één brontekstregel die legitiem meerdere edges uitzendt, parameterbindingen gemodelleerd als assignments, talen met een reference-per-identifier-patroon). Daarom samplen we met twee seeds en kruiscontroleren we, en daarom wordt een meningsverschil tussen de rechter en de fixtures behandeld als het meest interessante signaal, geen definitief oordeel — soms is de fixture het ding dat fout zit.

We zijn ook eerlijk over het doel. Het doel is nul echte fouten, punt — maar “nul” is een richting waarin we blijven werken, taal voor taal, geen vakje dat je afvinkt. Er is altijd nog een repo met een ander idioom.

Verdiend, niet beweerd

Alles wat Maguyva voor een agent doet — een symbool vinden, een afhankelijkheid traceren, een vraag beantwoorden met geciteerde code — rust op de extractie eronder die klopt. Over 280 talen kan “klopt” niet worden beweerd; het moet voortdurend worden verdiend tegen echte code. De lus is hoe we het verdienen: een autonome steekproef-en-repareer-cyclus die zijn eigen metrieken met argwaan behandelt, elke wijziging bewijst, en elke fix omzet in een bescherming tegen de volgende regressie. Het is niet glamoureus. Het is het werk dat ons in staat stelt te zeggen “we ondersteunen jouw taal” en dat te menen. Groen is makkelijk. Correct is verdiend.

Zoeken met multimodale fusie: voor elke query de juiste retriever kiezen

Wed, 15 Apr 2026 00:00:00 GMT

Opmerking over het historische ontwerp: dit artikel uit april 2026 beschrijft het routeringsontwerp van toen, niet het huidige standaardgedrag. De correctie van september hieronder betreft alleen een meetclaim. Zie Hoe het werkt voor de huidige routering, voorinstellingen en expliciete modaliteitsinstellingen.

Een zoekquery is niet één ding.

“waar is parseConfig gedefinieerd” wil een exact symbool — één precieze locatie, snel. “hoe werkt authenticatie” wil betekenis — de spreiding aan gerelateerde code die een concept verklaart. “wat breekt er als ik deze functie verander” wil de afhankelijkheidsgraaf. “vind de string ECONNREFUSED” wil een letterlijke match, niets slims.

Grep is uitstekend voor letterlijke matches en nuttig om bepaalde referenties op te sporen, maar het is geen afhankelijkheidsgraaf en het begrijpt geen betekenis. Embeddings dekken de semantische kant, maar ze zijn het verkeerde gereedschap voor exacte strings en impactanalyse. De meeste codezoektools kiezen één engine en laten elke query met die keuze leven. Maguyva kiest niet. Het bepaalt wat voor soort vraag je stelde, en mengt dan vier retrievers in de verhouding die bij die vraag past.

Vier modaliteiten

Onder de motorkap zijn er vier onafhankelijke manieren om code te vinden:

semantic — vectorzoeken over Voyage binary embeddings; vindt code op betekenis.
text — trigram-matching; vindt letterlijke tekst, foutmeldingen, exacte identifiers.
structural — AST-queries; vindt definities, signatures en taalconstructies.
graph — de afhankelijkheidsgraaf; vindt callers, callees en impactradius.

Elk is sterk op een andere klasse vragen. De truc is bepalen hoeveel je elk moet vertrouwen voor de query die voor je ligt.

Intentieclassificatie

Voordat er enige retrieval draait, sorteert een lichtgewicht classifier de query in één van zes intenties, met een confidence-score. Die is bewust goedkoop — geordende heuristieken, eerste match wint — omdat hij op het hot path draait en slechts een milliseconde of twee toevoegt:

begint met def , class , func , import … → find_definition (confidence 0,95)
“who calls”, “usages of”, “references to” → find_references (0,90)
“impact”, “blast radius”, “what depends on” → impact_analysis (0,90)
een geciteerde "string" of een errortoken zoals traceback → exact_match (0,85–0,90)
een CamelCase- of snake_case-identifier → find_definition (0,60–0,80)
“how”, “why”, “explain”, “architecture” → understand_code (0,75)
niets matcht → understand_code, lage confidence (0,40)

Elke intentie draagt een gewichtsprofiel over de vier modaliteiten. Dit zijn de echte cijfers:

Intent	semantic	text	structural (AST)	graph
find_definition	0,2	0,1	0,6	0,1
find_references	0,1	0,2	0,2	0,5
understand_code	0,5	0,2	0,2	0,1
find_similar	0,4	0,3	0,2	0,1
impact_analysis	0,1	0,1	0,1	0,7
exact_match	0,0	0,9	0,1	0,0

Dus “waar is parseConfig gedefinieerd” leunt zwaar op AST (0,6). “hoe werkt auth” leunt op semantische vectoren (0,5). “wat hangt hiervan af” is bijna volledig graph (0,7). “vind ECONNREFUSED” is bijna volledig trigram (0,9), waarbij het embeddingmodel volledig is uitgeschakeld — omdat semantische gelijkenis precies het verkeerde gereedschap is voor een exacte string.

Het snelle pad, en het samengevoegde pad

Wanneer de classifier zeker is — score ≥ 0,85 — en het om een gangbare query gaat, slaat Maguyva fusie volledig over en routeert direct naar de enkele dominante modaliteit. “waar is X gedefinieerd” heeft geen vier retrievers nodig; het heeft de AST-index nodig, nu meteen. Dat directe pad wordt teruggerapporteerd als fusion_strategy: "direct".

Alles wat ambigu is gaat door fusie. De vier (of drie, bij de standaardpreset) modaliteiten draaien parallel, elk met een eigen gerangschikte lijst, en we combineren ze.

Weighted Reciprocal Rank Fusion

Heterogene retrievers samenvoegen is lastiger dan het klinkt: een cosine similarity van 0,82 en een trigramscore van 137 en een graafcentraliteit van 0,004 zitten niet op dezelfde schaal, dus je kunt ze niet zomaar optellen. Reciprocal Rank Fusion omzeilt het probleem door de ruwe scores weg te gooien en alleen de rank te behouden die elke engine toekende. De bijdrage van een resultaat uit één modaliteit is:

contribution = weight × 1 / (k + rank + 1)

waarbij rank zijn positie is in de lijst van die modaliteit en k een smoothing-constante is. Bijdragen worden opgeteld over modaliteiten heen voor elk resultaat dat door meer dan één engine werd gevonden — overeenstemming tussen retrievers stijgt van nature naar boven. We gebruiken k = 40 bij de standaardpreset en 60 bij thorough (quick draait alleen semantisch, dus fusie komt daar nooit in beeld). Het oorspronkelijke RRF-werk kwam uit op k = 60 voor retrieval voor algemeen gebruik; wij hanteren standaard een iets scherpere afstelling, wat topgerangschikte overeenstemming tussen modaliteiten iets meer gewicht geeft — en we raden af om er handmatig aan te sleutelen.

Daarbovenop dragen resultaten een boost op graafbelang. Een hub — een functie waar de hele codebase op leunt — hoort een obscuur blad te overtreffen, zelfs bij gelijke tekstuele relevantie, dus vermenigvuldigen we elke bijdrage met:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

Centraliteit komt van de vooraf berekende PageRank-/degree-metrieken van de pipeline, en de boost wordt begrensd op 1,5× zodat een populaire functie een relevantere obscure functie niet volledig kan begraven. Tot slot degraderen we resultaten uit vendor-, build- en archiefpaden, en dedupliceren we naar het beste chunk per bestand.

Wat nog altijd niet perfect is

De intentieclassifier is een verzameling regexes, geen getraind model. Hij verwerkt veelvoorkomende queryvormen met heuristieken, en een dubbelzinnige query valt terug op understand_code en een semantisch georiënteerde mix. Een eerdere versie van dit artikel beschreef een daling van het percentage zoekopdrachten zonder resultaten van ongeveer 15% naar minder dan 5% als behaald. Het voorstel uit december 2025 vermeldde in werkelijkheid een geschatte uitgangswaarde en een doel; er is geen ondersteunende queryverzameling of meetrapport verstrekt. We trekken die claim van een behaalde verbetering in; zie het bronbewijs en de correctie. We hebben de classifier niet vervangen door een getraind model, omdat de goedkope versie snel en goed genoeg is voor de beoogde routeringsrol, en omdat een classifier die zelfverzekerd fouten maakt erger is dan een eerlijke fallback. De gewichten zelf zijn handmatig gekozen priors, niet geleerd uit klikdata die we niet verzamelen.

Stel de vraag, niet de tool

Een agent zou niet hoeven weten of hij naar grep of embeddings of de call graph moet grijpen — hij zou zijn vraag in gewone taal moeten kunnen stellen en het juiste antwoord moeten krijgen. Multimodale fusie is wat find_symbol, semantisch zoeken en afhankelijkheidsanalyse via één query-interface beschikbaar maakt: het systeem leest de vorm van de vraag en stelt in stilte de juiste retriever ervoor samen. Het model dat de embeddings scoort, is belangrijk, maar weten wanneer je ze niet moet gebruiken is dat net zo goed. Voor elke query het juiste gereedschap kiezen, is een eigen soort kwaliteit, en dat is er een die we liever zelf dragen dan doorschuiven naar de aanroeper.

// you bring the question. it brings the tools.

Agent-observability: hooks, Alloy en Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Agentsystemen falen op vreemde manieren.

Soms is het model het probleem. Soms is de tool het probleem. Soms is je MCP-server prima in orde, maar koos de agent de verkeerde specialist, besteedde hij de halve sessie aan shellwerk dat je niet had verwacht, of joeg hij er ongemerkt geld doorheen in een lus die van buitenaf productief leek.

Als je het verschil niet kunt zien, beheer je eigenlijk geen agentsysteem. Je gokt.

Dus bouwden we een observability-stack voor onze eigen workflow: Claude Code, Codex, Claude-hookevents, Codex-notifyevents, native OpenTelemetry, Grafana Alloy, en aan de andere kant Grafana Cloud.

Het interessante deel is niet “we hebben een dashboard gemaakt”. Het interessante deel is dat we telemetrie moesten opsplitsen in twee verschillende streams, omdat geen enkele feed op zich het volledige beeld gaf.

Het probleem: agenttelemetrie is gefragmenteerd

Moderne coding agents zenden al enige telemetrie uit. Dat helpt, maar het is niet genoeg.

Native OTEL is goed in het beantwoorden van vragen zoals:

Hoeveel requests hebben we gedaan?
Wat heeft een sessie gekost?
Waar bevinden zich de spans en traces?
Piekte de latency?

Het is veel minder goed in het beantwoorden van vragen zoals:

Op welke MCP-server leunde de agent?
Zat deze fout in Bash, een ingebouwde bestandstool, of een MCP-call?
Welke skill werd daadwerkelijk geactiveerd?
Welk type subagent werd ingezet?
Deed de sessie nuttig werk, of ploeterde ze maar wat?

Die tweede categorie vragen ligt dichter bij hooks dan bij traces.

Maar het omgekeerde geldt ook: sommige van de belangrijkste performancevragen liggen dichter bij traces dan bij hooks.

Als je wilt weten waar de latency zich daadwerkelijk opstapelde, welke spans traag waren, of de sessie tijd besteedde aan modelcalls versus tooluitvoering, heb je trace-data nodig naast semantische events.

De architectuur waar we op uitkwamen

We draaien twee telemetriepaden naast elkaar.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Die opsplitsing is bewust.

Het is ook asymmetrisch. Claude Code geeft ons een veel rijker lifecycle-hookoppervlak. Codex geeft ons native OTEL plus een notify-oppervlak, dus normaliseren we minder gedetailleerde turn-completion-events naar hetzelfde logschema in plaats van te doen alsof beide runtimes dezelfde controls bieden.

Native OTEL geeft ons de basisstream: logs en traces van de runtime zelf, plus metrics waar de runtime die daadwerkelijk uitzendt.

Hook- en notify-events geven ons de semantische laag: dingen zoals PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, en de geclassificeerde metadata waar het ons daadwerkelijk om gaat bij het debuggen van agentgedrag. Claude Code levert hier de rijkere eventstream. Codex levert een minder gedetailleerde maar nog altijd nuttige genormaliseerde stream.

Waarom hooks überhaupt bestaan

Onze hookpipeline verrijkt events voordat ze Loki bereiken.

In plaats van simpelweg te zeggen “er is een tool uitgevoerd”, classificeren we het event in velden zoals:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: welke MCP-backend de call afhandelde
bash_cli: de shellcommandofamilie
subagent_type: welk type specialist werd ingezet
agent_tool: of de bron Claude Code of Codex was

Dat betekent dat we vragen kunnen stellen die operationeel van belang zijn:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Dat zijn geen velden voor de sier. Ze maken het verschil tussen “de agent voelde traag” en “de agent besteedde de laatste tien minuten aan shell-zware git-operaties met een hoog toolfoutpercentage.”

Eén implementatiedetail dat vreemder oogt dan het is: de gedeelde Loki-stream gebruikt nog altijd service_name="claude-code-hooks" als label, zelfs wanneer het event van Codex kwam. De echte opsplitsing tussen runtimes gebeurt op agent_tool.

Waarom Alloy in het midden zit

Grafana Alloy is in deze opzet niet zomaar een forwarder. Het is de beleidsgrens.

We wijzen de native OTEL-stream van Claude Code en Codex naar een lokale Alloy-proxy op localhost:4318, en laten Alloy vervolgens de payload opschonen voordat die wordt doorgestuurd naar Grafana Cloud.

Dat is belangrijk omdat ruwe agenttelemetrie vol zit met high-cardinality-velden die nuttig zijn voor analyse maar vreselijk als geïndexeerde labels:

session_id
prompt_id
tokenaantallen
duraties
tool-parameterblobs

Als je alles indexeert, krijg je een labelexplosie en een rotdag.

Dus doet Alloy drie dingen voor ons:

Houdt een zeer kleine set low-cardinality-labels geïndexeerd.
Verplaatst ruisrijke maar nuttige velden naar gestructureerde metadata.
Laat pure ruis volledig vallen.

Het belangrijkste idee is simpel: observeer meer, indexeer minder.

Waarom de hookstream Alloy omzeilt

De hookstream is al gevormd voor Loki.

Tegen de tijd dat send_event.py een event pusht, hebben we al besloten welke velden een labelbehandeling verdienen en welke thuishoren in de gestructureerde JSON-body. Die stream gaat rechtstreeks naar de OTLP-gateway van Grafana Cloud, zonder nog een keer via Alloy te lopen.

Het systeem heeft dus een duidelijke taakverdeling:

Alloy temt de ruwe native OTEL-stream.
Hookverrijking maakt semantische events doorzoekbaar.

Dat houdt de architectuur eenvoudiger dan proberen alles via één pad te forceren.

Wat het dashboard daadwerkelijk laat zien

De onderstaande screenshot komt van een van de observability-dashboards achter onze agentworkflow. Het is geen benchmark, en de cijfers zijn slechts een momentopname. Het gaat om de vorm van de data: activiteitenfeed, toolcalls, fouten, prompts, en uitsplitsingen per agent, ingebouwde tools, MCP-gebruik, shellcommando’s en skills.

Het nuttige deel is dat dit dashboard op dezelfde Grafana-stack leeft als de rest van de agenttelemetrie. We kunnen filteren op bronagent en toolfamilie en over runtimes heen kijken zonder voor elk systeem een ander observability-verhaal te verzinnen.

Een van de live dashboards achter onze agentworkflow. Deze screenshot is slechts één momentopname van een gedeelde Grafana-stack die ook telemetrie ontvangt van onze andere agent-runtimes en -systemen. Klik op de afbeelding voor de versie in volledige resolutie.

Waarom traces belangrijker zijn dan ze op het eerste gezicht lijken

Logs vertellen ons welke categorie werk plaatsvond. Traces vertellen ons hoe het werk zich in de tijd ontvouwde.

Dat onderscheid is belangrijk in agentsystemen omdat “traag” te bot is om nuttig te zijn.

Een trace kan ons vertellen of de pijn kwam van:

modellatency
tooluitvoeringstijd
herhaalde retries
één bijzonder dure MCP-interactie
een lange staart aan kleine operaties die afzonderlijk onschuldig leken

In de praktijk gebruiken we de hookstream en Tempo-traces samen.

Hooklogs beantwoorden: wat voor soort gebeurtenis vond er plaats?
Traces beantwoorden: waar ging de tijd naartoe?

Die combinatie is wat observability verandert van een dashboard in een verklaring.

Waar Codex in past

Codex maakt deel uit van dezelfde stack, maar is niet identiek aan Claude Code.

Voor Codex koppelen we twee onderdelen:

Native OTEL van Codex naar Alloy
Een notify-webhook naar codex_notify.py, die turn completions afbeeldt op hetzelfde Loki-schema dat we voor hookevents gebruiken

Dat geeft ons een uniform filter zoals agent_tool="codex-cli" binnen dezelfde logstream.

De eerlijke kanttekening: de notify-payload van Codex is momenteel minder gedetailleerd dan de hookpayload van Claude Code, omdat het niet hetzelfde soort integratieoppervlak is. In onze huidige opzet kunnen Codex-turn-completions worden genormaliseerd naar het gedeelde schema, maar rijke tool-voor-tool-extractie werkt nog altijd beter in de native OTEL-stream dan in de notify-bridge.

Dat is geen reden om deze post te vermijden. Het is precies het punt van deze post. Echte observability-systemen worden opgebouwd uit imperfecte signalen.

Grafana via MCP verandert het spel

De grotere verschuiving is dat Grafana niet alleen een plek is die mensen in een browser bezoeken.

In deze repo stellen we Grafana ook beschikbaar via MCP. Dat betekent dat een agent Loki, Prometheus en Tempo rechtstreeks kan bevragen, in plaats van te wachten tot een mens eerst handmatig de dashboards inspecteert.

Dat maakt van observability een actieve input voor de workflow.

Een agent kan vragen:

Welke toolfamilies faalden het meest in het afgelopen uur?
Welke MCP-server domineerde een sessie?
Verminderden recente wijzigingen het aantal toolfouten, of verplaatsten ze het werk alleen naar meer shell-zware paden met dezelfde fouten?
Welke traces vertonen de hoogste latency of herhaalde retries?

Zodra je dat hebt, ben je heel dicht bij een zelfverbeteringslus.

Van dashboard naar feedbacklus

Dit is het deel dat we het interessantst vinden.

Zodra de observability-stack bevraagbaar is vanuit de agentlaag, houdt telemetrie op een passief rapportageoppervlak te zijn en wordt het een besturingssignaal.

De lus ziet er zo uit:

Agentactiviteit genereert traces, metrics en verrijkte hooklogs.
Grafana slaat het bewijsmateriaal op in Loki, Tempo en Prometheus waar metrics bestaan.
Agents bevragen dat bewijsmateriaal via Grafana MCP.
Het systeem identificeert een slechte toolmix, broze skills, zwakke routering, of shell-zware workflows die steeds vermijdbare fouten blijven produceren.
Agents of operators passen prompts, agentconfiguraties, skillbeschrijvingen, routeringsregels of tooltoegang aan.
De volgende sessie produceert een nieuwe telemetrievorm, en de cyclus herhaalt zich.

Zo beweeg je van “interessant dashboard” naar “meetbaar verbetersysteem”.

Het doel is niet om één toolcategorie te maximaliseren. Het doel is uit te komen op de juiste mix van CLI, ingebouwde tools, MCP-calls en skills voor het werk dat daadwerkelijk wordt gedaan.

Wat dit ons laat beantwoorden

Zodra beide runtimes in dezelfde Grafana-stack terechtkomen, kunnen we operationele vragen veel sneller beantwoorden:

Concentreren fouten zich in één toolfamilie?
Veroorzaken shell-zware workflows vermijdbare fouten op plekken waar een hoger-niveau-tool zou moeten bestaan?
Welke MCP-servers dragen de werklast?
Betalen we voor agentactiviteit die geen betekenisvolle voortgang oplevert?
Is een sessie ongezond vanwege het model, de tools, of de orchestratielaag?

Dit is vooral nuttig in multi-agent-workflows, waar “de agent was bezig” je bijna niets vertelt.

Als één specialist steeds wordt ingezet en hoge foutpercentages oplevert, is dat een routerings- of prompt-vormgevingsprobleem.

Als één MCP-server alle calls domineert, kan dat goede architectuur zijn, of een teken dat al het andere dood gewicht is.

Als toolfouten pieken terwijl de kosten hoog blijven, heb je een operationeel probleem, geen kwaliteitsprobleem.

Als shellwerk steeds op voorspelbare, vermijdbare manieren mislukt op plekken waar een hoger-niveau-tool zou moeten bestaan, is dat een productsignaal.

Als één skill voortdurend wordt geactiveerd maar de resultaten niet verbetert, is dat een prompt- of routeringssignaal.

De echte les

De diepere les hier is dat agent-observability zowel runtime-telemetrie als workflow-telemetrie nodig heeft.

Runtime-telemetrie vertelt je wat het systeem deed.

Workflow-telemetrie vertelt je wat de agent dacht te doen.

We hebben beide nodig.

Als je alleen traces en counters bijhoudt, mis je de semantische laag. Als je alleen hookevents bijhoudt, mis je latency, spans en het bredere runtimebeeld.

En als je beide bijhoudt maar ze nooit terugvoert naar de agentlaag, heb je monitoring, geen aanpassing.

Die combinatie is wat het systeem uitlegbaar genoeg maakt om te beheren en afstembaar genoeg om te verbeteren.

Wat nog altijd niet perfect is

Er zijn nog altijd ruwe randjes.

Niet elk hookevent bevat de duratie- en tokendata die we zouden willen.
Sommige van de beste timingweergaven komen nog altijd van Tempo-traces, niet van de hooklogs.
Codex is momenteel semantisch minder rijk dan Claude Code in de verrijkte eventstream.
De dashboardscreenshot is een live operations-oppervlak, geen gepolijst marketingartefact.

Dat laatste punt is bewust. We laten liever het echte instrumentenpaneel zien dan doen alsof agentsystemen magisch vanzelfsprekend zijn.

Waarom dit belangrijk is voor Maguyva

Maguyva draait om agents betere code-intelligentie geven. Maar zodra agents daadwerkelijk nuttig werk doen, duikt er meteen een nieuwe vereiste op: je moet kunnen zien hoe ze zich gedragen.

Zoekkwaliteit, routeringskwaliteit, toolselectie en contextefficiëntie worden allemaal observeerbare vraagstukken.

Daarom denken we dat dit de moeite van het beschrijven waard is. De toekomstige agentstack is niet alleen prompts en tools. Het is prompts, tools, en de instrumentatielaag die je vertelt of het geheel werkt.

Als je serieuze agentworkflows bouwt, is observability geen optionele infrastructuur. Het is onderdeel van het product.

De lus minen: hoe wijzigingen institutioneel geheugen worden

Tue, 03 Feb 2026 00:00:00 GMT

Cijfers in deze post weerspiegelen het systeem op het moment van publicatie (februari 2026). Zie onze teampagina voor actuele cijfers.

Elk engineeringteam staat voor dezelfde uitdaging: wijzigingen gebeuren voortdurend, maar het waarom achter die wijzigingen verdwijnt. Zes maanden later vraagt iemand “waarom hebben we DuckDB gekozen voor pipelinestages?” en het antwoord leeft alleen in het hoofd van wie die beslissing nam — als die persoon er nog is.

We hebben een miningworkflow gebouwd die deze lus sluit. Wijzigingen stromen via git-commits, worden verwerkt door onze miningpipeline, worden gestructureerde changelog-items en architecturale beslissingsdossiers, en vloeien vervolgens terug naar onze AI-agents via CLI-queries. Het resultaat: institutioneel geheugen dat zowel mensen als AI kunnen raadplegen.

Het probleem: beslissingen verdampen

Bekijk een typisch scenario. Een developer maakt een commit:

feat(canonical): add DuckDB runtime for pipeline stages

Deze commit vertegenwoordigt een significante architecturale keuze. Het team evalueerde opties, woog trade-offs af en koos om specifieke redenen voor DuckDB. Maar al die context leeft in:

Een Slack-thread (waarschijnlijk verwijderd)
Iemands geheugen (zeker vervagend)
Een comment in de code (misschien, als je geluk hebt)

Drie maanden later vraagt een nieuw teamlid: “Moet ik DuckDB of SQLite gebruiken voor deze nieuwe stage?” Zonder institutioneel geheugen vinden ze het wiel opnieuw uit of maken ze inconsistente keuzes.

De lus: van commits naar context

Onze miningworkflow transformeert git-geschiedenis naar doorzoekbare kennis:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

Het belangrijkste inzicht: zowel changelogs als architecturale beslissingen stromen uit dezelfde git-geschiedenis, verwerkt via één uniforme pipeline. Dat zorgt ervoor dat niets tussen wal en schip valt.

Hoe mining werkt

Stap 1: de index synchroniseren

uv run orkestra mine sync

Dit commando scant de git-geschiedenis en bouwt een index van alle commits. Het extraheert gestructureerde signalen uit elke commit:

Conventional-commit-type (feat, fix, chore, docs)
Scope (welk package of gebied)
Breaking-change-markers
Aangeraakte bestanden en complexiteitsmetrieken

Stap 2: dekkingsstatus controleren

uv run orkestra mine status

Dit is hoe onze huidige status eruitziet:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15.637 commits verwerkt. 476 werden architecturale beslissingen. 6.799 werden changelog-items. Elke commit geclassificeerd.

Stap 3: kandidaten voor review ophalen

uv run orkestra mine candidates --limit 50 --full

Dit brengt commits naar boven die nog niet zijn verwerkt, met volledige context voor classificatie:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

De signalen helpen bij de classificatie: is_releasable_type: true suggereert dat dit in de changelog moet verschijnen. Het grote aantal insertions en de infrastructuurbestanden suggereren dat het ook een architecturale beslissing kan zijn.

Stap 4: commits classificeren

Hier splitsen twee paden zich: changelog-items en architecturale beslissingen.

Voor changelog-items:

uv run orkestra mine classify abc123 --changelog added

Dit legt vast dat commit abc123 in de changelog moet verschijnen onder de categorie “Added”.

Voor architecturale beslissingen:

Vraag eerst een echte decision-ID op:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Classificeer vervolgens met de decision-ID:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Dit koppelt de commit aan een beslissingsdossier dat wordt aangemaakt of bijgewerkt.

Voor batchverwerking (wat we in de praktijk doen):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Het JSONL-formaat ondersteunt beide domeinen in één doorgang:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Stap 5: outputs renderen

uv run orkestra registry changelog render --package <pkg>

Dit genereert per-package CHANGELOG.md-bestanden vanuit het ledger. De changelogs zijn afgeleide artefacten — verwijder ze en ze worden perfect opnieuw gegenereerd vanuit het bron-ledger.

De structuur van het beslissingsdossier

Geëxtraheerde beslissingen worden YAML-bestanden met rijke metadata:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Elke beslissing verwijst terug naar zijn bron-commits. Elke beslissing specificeert welke bestanden hij raakt. Relaties tussen beslissingen zijn expliciet.

CLI-integratie: institutioneel geheugen bevragen

Hier sluit de lus zich. Agents kunnen beslissingen bevragen via de CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Geeft beslissingen over retrylogica, foutafhandeling, herstelpatronen.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Geeft het complete beslissingsdossier met context, onderbouwing en impact.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Toont welke architecturale keuzes recent zijn gemaakt.

Hoe agents dit gebruiken

De baseline-instructies van onze orchestrator omvatten:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Wanneer een agent wordt gevraagd iets te implementeren dat met DuckDB te maken heeft, kan hij eerst controleren:

uv run orkestra registry decisions search --query "DuckDB"

En DEC-PL-142 ontdekken, waarbij hij leert:

Waarom we voor DuckDB kozen (context)
Hoe je het correct gebruikt (agent_guidance)
Welke bestanden je moet bekijken (files)
Welke gerelateerde beslissingen bestaan (related)

De agent vindt het wiel niet opnieuw uit. Hij bouwt voort op gevestigde patronen.

De Drie-Vragen-Test

Niet elke commit verdient een beslissingsdossier. We gebruiken de Drie-Vragen-Test om te filteren:

Was deze beslissing moeilijk te nemen? Vereiste het significante analyse, afweging van trade-offs, of discussie?
Is het kostbaar om te wijzigen? Zou het terugdraaien van deze beslissing significant herwerk vereisen?
Heeft het systeembrede impact? Raakt het meerdere packages of vestigt het patronen die anderen zullen volgen?

Als een commit “ja” antwoordt op minstens één van deze vragen, is hij een kandidaat voor beslissingsextractie. Ons typische percentage: 1-4 beslissingen per 100 commits (ongeveer 1-4%).

Voor changelog-items ligt de lat lager: elke gebruikersgerichte wijziging (features, fixes, verbeteringen) wordt vastgelegd. Interne chores, documentatie-updates en refactors worden doorgaans overgeslagen. Ons typische percentage: 30-50 changelog-items per 100 commits.

Dataopslag: append-only ledgers

Het miningsysteem gebruikt append-only JSONL-ledgers voor conflictvrije multi-agent-werking:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Het JSONL-formaat met merge=union in .gitattributes betekent dat meerdere agents tegelijk commits kunnen classificeren zonder merge-conflicten. Elke regel is onafhankelijk.

Validatiegates

Voor elke miningsessie draaien we validatie:

uv run orkestra mine validate --quick

Dit controleert:

Geldigheid van het SHA-formaat
Naleving van het decision-ID-formaat
Geen dubbele items voor dezelfde SHA
Dat gerefereerde beslissingen daadwerkelijk bestaan

Na classificatie valideren we opnieuw voordat we wijzigingen committen.

Waarom dit ertoe doet

De feedbacklus die we hebben gebouwd, lost verschillende problemen op:

Voor nieuwe teamleden: In plaats van te vragen “waarom hebben we X gedaan?” kunnen ze het beslissingsregister doorzoeken. De context blijft bewaard.

Voor AI-agents: Ze opereren niet in een vacuüm. Ze kunnen institutionele kennis bevragen voordat ze aanbevelingen doen. Wanneer hun wordt gevraagd een nieuwe pipelinestage toe te voegen, kunnen ze het DuckDB-patroon ontdekken en volgen.

Voor architecturale consistentie: Beslissingen zijn expliciet en doorzoekbaar. Wanneer iemand een aanpak voorstelt die in strijd is met een bestaande beslissing, kan het systeem het conflict naar boven halen.

Voor changeloggeneratie: Release notes zijn geen last-minute gehaast geregel. Ze zijn een bijproduct van continue classificatie tijdens de ontwikkeling.

Voor onboarding: Nieuwe agents erven de volledige context van de codebase. Ze zien niet alleen de code — ze zien ook de beslissingen die haar vormgaven.

Huidige status

Op dit moment:

15.637 commits verwerkt door de pipeline
476 architecturale beslissingen geëxtraheerd en gedocumenteerd
6.799 changelog-items vastgelegd
100% dekking over beide domeinen

Elke commit sinds we begonnen is geclassificeerd. Het institutionele geheugen is compleet en doorzoekbaar.

Aan de slag

Als je iets vergelijkbaars wilt implementeren:

Begin met conventional commits. De miningpipeline werkt het best wanneer commits gestructureerde prefixes hebben (feat:, fix:, chore:).
Definieer je domeinen. Wij gebruiken domeinen zoals pipeline, agent-design, observability, data-modeling. Die organiseren beslissingen per gebied.
Bouw de classificatiegewoonte op. Mining werkt wanneer teams regelmatig commits classificeren. Batchverwerking met LLM-ondersteuning helpt bij het opschalen.
Maak beslissingen bevraagbaar. De waarde stapelt zich op wanneer agents beslissingen kunnen doorzoeken via de CLI. Structureer je output voor machineconsumptie.
Sluit de lus. Beslissingen moeten toekomstig werk beïnvloeden. Neem decision-referenties op in agentinstructies en code-reviewchecklists.

Het doel is geen perfecte documentatie. Het doel is het waarom achter wijzigingen toegankelijk maken voor zowel mensen als AI, vandaag en over zes maanden. Wanneer wijzigingen institutioneel geheugen worden, bouwen teams voort op gevestigde patronen in plaats van ze opnieuw uit te vinden.

De miningworkflow maakt deel uit van onze orchestration engine, specifiek de context engine-module in ons orchestration-package.

Skill mining: van 3.500 kandidaten naar 466 capaciteiten

Tue, 27 Jan 2026 00:00:00 GMT

Cijfers in deze post weerspiegelen het systeem op het moment van publicatie (januari 2026). Zie onze teampagina voor actuele cijfers.

Het probleem van de 3.500 skills

Toen we begonnen met het bouwen van een agent-orchestratiesysteem, stonden we voor een interessante uitdaging: er zijn duizenden potentiële skills verspreid over het AI-ecosysteem. GitHub-repositories, vendordocumentatie, communityprojecten, interne patronen — skills bestaan overal. Maar welke zijn belangrijk? Welke werken? En hoe onderhoud je een coherente skillbibliotheek die agents daadwerkelijk kunnen gebruiken?

Ons antwoord: een systematische mining- en ingestielus.

De cijfers vandaag

Iets meer dan drie maanden nadat Anthropic Agent Skills lanceerde op 16 oktober 2025, is dit waar we stonden toen deze post werd gepubliceerd op 27 januari 2026:

Metriek	Aantal
Geïdentificeerde kandidaten	3.500+
Overgenomen skills	466
Vendor-skills	373
Interne skills	93
Actieve vendors	25+
Gemiddeld aantal tokens per skill	2.834
Gerefereerde tools	89
Unieke tags	635

We hebben meer dan 3.500 skillkandidaten beoordeeld. We hebben er 466 overgenomen. Dat is een adoptiepercentage van 13% — en die selectiviteit is met opzet.

Het kennis-tiersysteem

Niet alle skills zijn gelijk. We organiseren ze in vijf kennislagen (K0-K4), elk met een andere reikwijdte van toepasbaarheid:

K0: Foundations (universeel)

Skills die elke agent zou moeten hebben. Deze vertegenwoordigen “goede denker”-capaciteiten die overal werken.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0-skills zijn overdraagbaar naar elk project, elk domein, elke stack. Ze coderen universele cognitieve patronen.

K1: Identities (discipline)

“Goede engineer”- of “goede onderzoeker”-skills die van toepassing zijn over projecten heen binnen een discipline.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domains (vakexpertise)

“Goede database-expert”- of “goede security-engineer”-skills die overdraagbaar zijn binnen een vakgebied.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (technologie)

“Goede Supabase-gebruiker”- of “goede Cloudflare-developer”-skills voor specifieke technologiestacks.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Project (organisatie)

Skills specifiek voor onze organisatie en workflows.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

De mininglus

Fase 1: ontdekking

Skills komen overal vandaan:

Vendor-repositories: AWS, Anthropic, Cloudflare, Supabase en communitybijdragers publiceren skillcollecties. We volgen 25+ vendor-roots.

Communityprojecten: GitHub staat vol met Claude Code-templates, agentpatronen en workflowdefinities.

Interne patronen: Terwijl ons team problemen oplost, ontstaan patronen. Die worden geformaliseerd tot skills.

Documentatiemining: technische documentatie bevat vaak impliciete skills — procedures, checklists, beslisbomen.

Ontdekking is continu. We gebruiken een skillbacklog om kandidaten bij te houden vóór formele evaluatie.

Fase 2: evaluatie

Elke kandidaat wordt aan dezelfde beoordelingscriteria getoetst:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Aan alle vijf productcriteria moet worden voldaan. Daarom wordt 87% van de kandidaten afgewezen.

Vervolgens doorloopt elke kandidaat een aparte trust review. We behandelen een officiële vendor-repository, een bekende community-maintainer en een willekeurige GitHub-repo niet als gelijkwaardige sources of truth.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Vertrouwde vendors krijgen een lichtere herkomstreview, maar geen vrijbrief. Niet-vertrouwde of onbekende bronnen krijgen een diepere handmatige audit, en we voeren gebundelde scripts pas uit nadat ze zijn gelezen, afgebakend en als veilig geclassificeerd.

Gap-analyse: vóór we iets overnemen, doorzoeken we ons register:

uv run orkestra skills search "<capability>"

Als we het al hebben, hebben we het niet nodig. Als we iets vergelijkbaars hebben, mergen we het misschien liever dan het over te nemen.

Scoren op diepgang en standaarden: we scoren ook hoe volledig een kandidaat het agent-skill-model gebruikt. Een losstaande SKILL.md kan nog altijd nuttig zijn, maar diepere skills zijn waardevoller wanneer ze instructies scheiden van referenties, scripts en assets, zoals agentskills.io aanmoedigt.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHub-sterren kunnen een credibility-score een beetje verhogen, maar ze redden nooit een oppervlakkige of onveilige skill. Een repo met veel sterren en één vage SKILL.md met ondoorzichtige scripts scoort lager dan een kleinere repo met een precieze beschrijving, samengestelde references/, en atomaire helpers die de volledige skillcapaciteit daadwerkelijk benutten.

Structurele analyse: we controleren skillkwaliteit:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Als een kandidaat scripts bevat, wordt die review strenger. Een goede skill is niet alleen nuttig; hij moet ook leesbaar, afgebakend en veilig zijn om aan een agent te geven. Dat veiligheidsfilter alleen al diskwalificeert een aanzienlijk deel van verder interessante kandidaten.

Fase 3: ingestie

Wanneer een skill de evaluatie doorstaat, komt hij in het register. Maar skills worden nooit ongewijzigd overgenomen. Ze worden aangepast om in ons systeem te passen.

Aanpassingen bij overname:

Metadatanormalisatie: elke skill krijgt ons frontmatter-schema
K-tiertoewijzing: skills worden in de juiste kennislaag geplaatst
Tagverrijking: tags worden toegevoegd voor vindbaarheid
Tooldeclaratie: toegestane tools worden expliciet gedeclareerd
Sectie-uitlijning: inhoud wordt geherstructureerd om overeen te komen met onze template

Een typische skill-YAML na ingestie:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Fase 4: scopetoewijzing

Skills worden toegewezen aan scopes — categorieën die bepalen welke agents welke skills laden:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Agents declareren hun scopes, en skills worden automatisch toegewezen:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Fase 5: materialisatie

Skills bestaan niet als YAML in productie. Ze worden gerenderd naar SKILL.md-bestanden die Claude Code kan laden:

uv run orkestra sync

Dit commando:

Leest alle skill-YAML-definities
Rendert ze via Jinja-templates
Schrijft SKILL.md-bestanden naar .claude/skills/
Organiseert per K-tier (foundations/, identities/, domains/, stacks/, project/)

De uiteindelijke outputstructuur:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Het dormant-scope-patroon

Een van onze krachtigste patronen is “overgenomen-maar-niet-geladen”-skills. We noemen deze dormant scopes.

Denk aan scientific-computing-skills uit de k-dense-scientific-repository. We hebben er 120+ overgenomen die bio-informatica, scheikunde, quantum computing en klinische informatica bestrijken. Maar de meeste van onze agents hebben geen molecular docking of gene expression analysis nodig.

In plaats van alle 120 skills in elke agent te laden (wat contextvensters opblaast), gaan we als volgt te werk:

Neem de skills op met een specifieke scope (bijv. bioinformatics)
Houd ze dormant — geregistreerd maar niet geladen
Activeer ze alleen wanneer een agent die scope declareert

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Dit patroon laat ons 466 skills in het register hebben, terwijl typische agents er slechts 40-60 relevante laden.

Skilltypes

Skills komen in drie cognitieve patronen:

Workflow

Geordende procedurele stappen: “1. Doe X, 2. Dan Y, 3. Tot slot Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Discipline

Gedragsmatige guardrails: “Doe altijd X”, “Doe nooit Y”, “Geef de voorkeur aan Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist

Verificatiecriteria: “Bevestig X”, “Verifieer Y”, “Controleer Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Kwaliteitsgates

Elke skill moet validatie doorstaan voordat hij wordt uitgeleverd:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Beschrijvingen moeten 50-400 tekens zijn met triggerzinnen (“Use when…”, “When you need…”) zodat Claude Code weet wanneer hij ze moet voorstellen.

We valideren continu:

uv run orkestra validate --show-warnings

Het vendor-ecosysteem

Onze 373 vendor-skills komen van:

Provider	Skills	Domein
AWS Agent	19	Cloudservices
Anthropic	12	Documentgeneratie
Cloudflare	8	Edge computing
Supabase	5	Database
k-dense	100+	Scientific computing
silvainfm	4	Data science
Java Developer Kit	45+	Spring/Java
Vercel	1	Browserautomatisering

Elke vendor-root wordt gedeclareerd in metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Wanneer orkestra sync draait, worden vendor-skills gesymlinkt naar .claude/skills/vendor/ met hun provider-namespace.

Wat we hebben geleerd

Selectiviteit loont. Het is verleidelijk om alles over te nemen wat er nuttig uitziet. Maar elke skill kost tokens. Met gemiddeld 2.834 tokens per skill doet bloat snel pijn. Ons adoptiepercentage van 13% houdt agents slank.

Structuur maakt ontdekking mogelijk. Het K-tiersysteem is niet zomaar organisatie — het gaat om overdraagbaarheid. K0-skills kunnen overal worden hergebruikt. K4-skills zijn opzettelijk projectspecifiek. Deze helderheid helpt zowel mensen als agents vinden wat ze nodig hebben.

Dormant scopes schalen. Je kunt honderden skills overnemen zonder ze allemaal te laden. Scopes laten je een uitgebreid register bouwen terwijl de contextvensters van individuele agents behapbaar blijven.

Aanpassing bij overname is essentieel. Ruwe vendor-skills passen zelden in jouw systeem. Het ingestieproces — metadata toevoegen, tiers toewijzen, tags verrijken — laat externe skills intern werken.

Mining is continu. Het getal van 3.500 blijft groeien. Nieuwe vendor-repo’s verschijnen. Communitypatronen ontstaan. Interne workflows krijgen vaste vorm. De lus stopt nooit.

Wat komt hierna

We werken aan verschillende verbeteringen:

Geautomatiseerde gap-detectie: waarschuwen wanneer veelvoorkomende agentfouten kunnen worden verholpen door een niet-overgenomen skill
Skill-deprecationworkflows: formeel proces voor het uitfaseren van skills die zijn vervangen of niet worden gebruikt
Cross-skill-afhankelijkheden: expliciete declaratie van skillvereisten
Gebruiksanalytics: bijhouden welke skills agents daadwerkelijk aanroepen versus alleen laden

De skill-mininglus is infrastructuur. Het is niet glamoureus. Maar het is wat 41 agents coherent laat samenwerken met 466 capaciteiten terwijl ze binnen contextlimieten blijven.

Zo brengen we 3.500 kandidaten terug tot 466 skills. Niet door 3.000 te negeren — door ze systematisch te evalueren en alleen over te nemen wat werkt.

Wil je het skillsysteem in actie zien? Bekijk uv run orkestra skills list om ons huidige register te verkennen.

Progressive disclosure: CLI-vensters naar agentsystemen

Tue, 20 Jan 2026 00:00:00 GMT

Cijfers in deze post weerspiegelen het systeem op het moment van publicatie (januari 2026). Zie onze teampagina voor actuele cijfers.

Agentsystemen zijn van nature ondoorzichtig. Ze nemen beslissingen, roepen tools aan en coördineren werk over tientallen specialisten heen. Maar wanneer er iets misgaat — of wanneer je simpelweg wilt begrijpen wat er gebeurt — waar kijk je dan?

Het antwoord is progressive disclosure: een gelaagde interface die precies zoveel complexiteit onthult als je nodig hebt, precies wanneer je het nodig hebt.

Het ondoorzichtigheidsprobleem

Een modern agent-orchestratiesysteem kan het volgende hebben:

40+ gespecialiseerde agents, elk met eigen capaciteiten
700+ skills die interne automatisering en vendor-integraties omvatten
470+ architecturale beslissingen die gedrag vormgeven
Tientallen MCP-toolservers die externe capaciteiten bieden

Deze complexiteit is opzettelijk. Agents hebben toegang tot rijke context nodig — domeinkennis, code-intelligentie, databaseschema’s — om goede beslissingen te nemen. Maar diezelfde rijkdom creëert een zichtbaarheidsprobleem.

Hoe weet je welke agent databasemigraties afhandelt? Welke beslissingen hebben het rankinggedrag van het zoeksysteem gevormd? Tot welke tools heeft de architecture advisor toegang?

Zonder gestructureerde toegang rest je niets anders dan broncode te lezen of te hopen dat de documentatie actueel is.

Progressive disclosure als architectuur

Progressive disclosure is niet zomaar een UI-patroon. Het is een architecturaal principe: organiseer informatie in lagen, elk dieper dan de vorige, zodat gebruikers kunnen stoppen op het niveau dat hun vraag beantwoordt.

Voor agentsystemen vertaalt zich dat naar CLI-commando’s op toenemende diepte:

Niveau	Commando	Beantwoorde vraag
1	`orkestra system status`	Is alles gezond?
2	`orkestra agents list`	Welke agents bestaan er?
3	`orkestra agents info <name>`	Wat doet deze agent?
4	`orkestra decisions search`	Waarom werkt het op deze manier?
5	Maguyva MCP-tools	Laat me de code zien.

Elk niveau beantwoordt een natuurlijke vervolgvraag. Je hoeft zelden direct naar niveau 5 te springen.

Niveau 1: systeemgezondheid

De eerste vraag is altijd: werkt alles?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Eén commando. Vier cijfers. Genoeg om te weten dat het systeem geconfigureerd is en de registers gevuld zijn.

Als een agentaantal onverwacht daalt of skills niet laden, zie je dat hier het eerst. Geen logs induiken nodig.

Niveau 2: agentinventaris

Zodra je weet dat het systeem gezond is, is de volgende vraag: wat is er beschikbaar?

$ orkestra agents list

Dit geeft gestructureerde data terug — agentnamen, beschrijvingen, modelvoorkeuren, domeindekking. De output is standaard JSON, wat het makkelijk maakt om te pipen naar jq voor filtering:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Wil je agents die databasewerk afhandelen? Het zoekcommando maakt het specifieker:

$ orkestra agents search "database"

Dit scant namen, beschrijvingen en capaciteiten. Je vindt de juiste specialist zonder 40 agentdefinities te lezen.

Niveau 3: agent-deep-dive

Een relevant lijkende agent gevonden? Het commando info onthult alles:

$ orkestra agents info architecture-advisor

De output bevat:

Metadata: naam, categorie, modelvoorkeur, beschrijving
Domains: welke kennisgebieden deze agent bestrijkt
Identity: karaktertrekken (architect, strategist, knowledge-architect)
Toolgidsen: welke tooldocumentatie in de context wordt geïnjecteerd
Tools: de volledige lijst MCP-tools die deze agent beschikbaar heeft

Hier is een voorbeeld van wat je ziet:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Dit vertelt je precies wat de agent kan doen. Geen broncode nodig.

Niveau 4: decision archaeology

Agents gedragen zich volgens gedocumenteerde beslissingen. Wanneer je wilt begrijpen waarom iets op een bepaalde manier werkt, is het decisions-register de source of truth.

$ orkestra decisions search "agent"

Dit geeft de bijpassende architecturale beslissingen terug:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Van elke beslissing is de volledige herkomst vastgelegd — wanneer die werd genomen, waarom, welke trade-offs werden overwogen, welke commits haar implementeerden:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Dit is architecturale documentatie die actueel blijft omdat ze wordt gemined uit commits, niet handmatig onderhouden.

Niveau 5: directe code-intelligentie

Wanneer je de daadwerkelijke implementatie moet zien — niet metadata erover — bieden de MCP-tools van Maguyva directe toegang.

Vanuit een agentsessie:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Dit routeert automatisch over semantisch, tekst- en AST-zoeken om relevante code te vinden. Voor specifieke symbolen:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Voor afhankelijkheidsanalyse:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Dit zijn geen simpele grep-vervangers. Ze zijn graafbewust, semantisch geïndexeerd, en geïntegreerd met dezelfde code-intelligentie die de agents zelf aandrijft.

Uniform zoeken over registers heen

Soms weet je niet welk register het antwoord bevat. Het uniforme zoeken bestrijkt alles:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 matches over vijf registers. De samenvatting vertelt je waar je verder moet zoeken. Verwijder --summary voor gedetailleerde resultaten, of voeg --limit 5 toe om de output behapbaar te houden.

Waarom dit ertoe doet

Progressive disclosure gaat niet alleen over gemak. Het verandert hoe je met complexe systemen omgaat.

Debuggen wordt behapbaar. Wanneer een agent een onverwachte beslissing neemt, grep je niet door logs. Je controleert tot welke tools hij toegang heeft (agents info), welke beslissingen zijn gedrag vormgeven (decisions search), en traceert indien nodig de implementatie (intelligent_search).

Onboarding versnelt. Nieuwe teamleden hoeven niet de hele codebase te lezen. Ze beginnen met system status, verkennen met agents list, en gaan pas dieper wanneer ze iets tegenkomen dat ze niet begrijpen.

Documentatie blijft actueel. Omdat de CLI leest uit dezelfde registers die de agents configureren, is de output altijd accuraat. Er is geen drift tussen wat de documentatie zegt en wat het systeem doet.

De CLI als interface

We hadden een webdashboard kunnen bouwen. We hadden uitgebreide documentatie kunnen schrijven. In plaats daarvan bouwden we een CLI die leest uit de source of truth.

De CLI heeft voordelen:

Composeerbaar: pipe output door jq, integreer met scripts
Scriptbaar: automatiseer checks, genereer rapporten
Snel: geen paginaladingen, geen authenticatieflows
Accuraat: leest de daadwerkelijke configuratie, geen gecachte representatie

Voor systemen waar correctheid belangrijker is dan esthetiek, wint de CLI.

Je eigen progressive disclosure bouwen

Als je agentsystemen bouwt, bedenk dan hoe gebruikers ze zullen inspecteren:

Begin met health checks. Eén commando dat je vertelt of dingen werken.
Bied inventarisweergaven. Geef een overzicht van wat er bestaat voordat je uitlegt wat het doet.
Maak gerichte queries mogelijk. Zoeken verslaat bladeren op schaal.
Toon herkomst. Laat gebruikers beslissingen terugtraceren naar hun oorsprong.
Koppel aan code-intelligentie. Uiteindelijk moeten gebruikers de implementatie kunnen zien.

Elke laag beantwoordt een vervolgvraag. Bouw ze op volgorde van frequentie — de meeste gebruikers stoppen bij laag 2 of 3. Alleen powerusers bereiken laag 5.

Het doel is niet om alles bloot te leggen. Het is om precies te tonen wat nodig is, precies wanneer het nodig is. Dat is progressive disclosure toegepast op agentarchitectuur.

Ground Truths: AI-agents verankeren in de realiteit

Tue, 13 Jan 2026 00:00:00 GMT

Cijfers in deze post weerspiegelen het systeem op het moment van publicatie (januari 2026). Zie onze teampagina voor actuele cijfers.

AI-agents zijn opmerkelijk capabel. Ze kunnen redeneren, synthetiseren en genereren. Maar ze hebben een fundamentele zwakte: ze verzinnen dingen. Niet kwaadwillig, maar wel overtuigend. Een agent kan API-parameters bedenken die niet bestaan, verwijzen naar configuraties die nooit zijn gedefinieerd, of patronen uit zijn trainingsdata toepassen die in strijd zijn met jouw daadwerkelijke architectuur.

De standaardoplossing is “geef de agent meer context”. Maar context kan tegenstrijdig zijn. Documentatie raakt los van de implementatie. Comments liegen. Zelfs code kan misleidend zijn wanneer die wordt gelezen zonder de bedoeling te begrijpen.

We hadden iets explicieters nodig. Iets dat niet genegeerd of verkeerd geïnterpreteerd kon worden. Iets dat agents zou verankeren in verifieerbare realiteit.

We noemen ze Ground Truths.

Wat is een Ground Truth?

Een ground truth is een expliciete, geversioneerde feitelijke bewering die agents moeten respecteren. Het is geen documentatie. Het is geen comment. Het is een first-class entiteit in het systeem met:

Een unieke identifier (zoals GT-MAG-015 of GT-MAG-036)
Een levenscyclusstatus (current, tentative, of deprecated)
Een scope (platformbreed, package-specifiek, of domeingebonden)
Bewijs (bestandspaden, URL’s, of referenties die de bewering staven)
Agent guidance (expliciete do/avoid-instructies)

Hier is een voorbeeld uit ons Maguyva code-intelligentieplatform:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Dit is geen proza. Het is een contract. Wanneer een agent deze ground truth tegenkomt, weet hij:

Het standaardgedrag is deterministisch (lege resultaten, geen vage gissingen)
Er zijn specifieke parameters (find_similar, exact_match) met gedefinieerd gedrag
Er bestaat bewijs in specifieke bestanden dat geverifieerd kan worden
De bewering is geverifieerd op een specifieke datum

De anatomie van een Ground Truth-register

Ground truths leven in YAML-registers onder ai_assets/reference/ground_truths.yaml. Elk package of domein kan zijn eigen register hebben. De structuur is:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Het register bevat metadata over de collectie zelf, renderconfiguratie voor documentatiegeneratie, en de beweringen zelf. Elke bewering volgt een strikt schema dat wordt gevalideerd door Pydantic-modellen:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Hoe agents toegang krijgen tot Ground Truths

Ground truths worden via meerdere kanalen beschikbaar gesteld:

1. Gerenderde documentatie

Het commando orkestra sync transformeert YAML-registers naar leesbare markdown:

uv run orkestra sync

Dit genereert GROUND_TRUTHS.md-bestanden die worden opgenomen in de agentcontext. De gerenderde output groepeert beweringen op status en categorie:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI-zoeken

Agents met shelltoegang kunnen ground truths programmatisch doorzoeken:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

De zoekfunctie scoort matches over meerdere velden met gewogen relevantie:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Contextcompositie

Wanneer agents worden gerenderd vanuit YAML-definities, kan hun context verwijzen naar ground truth-registers:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Dit zorgt ervoor dat relevante ground truths worden geladen voordat de agent aan het werk gaat.

Categorieën van Ground Truths

Als we over onze registers heen kijken, clusteren ground truths in verschillende patronen:

Productprincipes

Beperkingen op wat het product wel en niet is:

“Maguyva is read-only ten aanzien van gebruikersrepositories; het enige niet-herbouwbare asset is de betaalde embeddings-cache.” (GT-MAG-001)

Architectuurgrenzen

Waar verantwoordelijkheden liggen en waarom:

“De grenzen tussen pipeline en Maguyva zijn opzettelijk: pipeline is herbruikbaar, Maguyva bevat codespecifieke logica, en CQRS scheidt stage-writes van server-reads.” (GT-MAG-006)

Anti-hallucinatieregels

Expliciete regels die toolcontracten deterministisch houden, zodat agents niet hoeven te gissen:

“Fuzzy symboolmatching gebeurt opt-in via find_similar=true. Standaardgedrag geeft lege resultaten voor niet-bestaande symbolen; exact_match=true dwingt strikte matching af en schakelt alle fuzzy fallbacks uit.” (GT-MAG-015)

Kwaliteitsgates

Standaarden die gehandhaafd moeten worden:

“Wijzigingen aan gedeelde infrastructuur (post_filters.py, relationship extractors, gedeelde handlers) MOETEN vóór commit worden gevalideerd tegen ALLE ondersteunde talen via full manifest generation. Een validatie voor één taal is onvoldoende voor gedeelde code.” (GT-MAG-036)

Codepatronen

Implementatievereisten:

“Gebruik asyncio.to_thread() voor CPU-bound werk in async-contexten; het verouderde loop.run_in_executor()-patroon mag niet worden gebruikt in nieuwe code.” (GT-MAG-018)

De levenscyclus van een Ground Truth

Ground truths zijn niet statisch. Ze evolueren via een gedefinieerde levenscyclus:

Tentative

Een voorgestelde waarheid die wordt geëvalueerd. De bewering is vastgelegd maar kan nog wijzigen:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current

Een geverifieerde waarheid die agents moeten respecteren. Het bewijs is gevalideerd:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated

Een waarheid die niet langer van toepassing is. Bewaard als historische referentie met een verwijzing naar wat ervoor in de plaats is gekomen:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Waarom niet gewoon documentatie?

Documentatie dient een ander doel. Ze legt uit. Ze onderwijst. Ze mag vaag zijn, mag kwalificaties gebruiken zoals “over het algemeen” of “doorgaans”.

Ground truths mogen niet vaag zijn. Het zijn beweringen. Ze gelden, of ze gelden niet.

Bekijk het verschil:

Documentatie: “De API geeft over het algemeen lege resultaten wanneer een symbool niet wordt gevonden, hoewel fuzzy matching in sommige configuraties ingeschakeld kan zijn.”

Ground Truth: “Standaardgedrag geeft lege resultaten voor niet-bestaande symbolen; exact_match=true dwingt strikte matching af en schakelt alle fuzzy fallbacks uit.”

De eerste is nuttig voor mensen die het systeem leren kennen. De tweede is bruikbaar voor agents die beslissingen nemen.

Agent guidance: wat te doen en te vermijden

Sommige ground truths bevatten expliciete agent guidance:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Dit neemt ambiguïteit weg. Een agent die dit leest, weet niet alleen wat waar is, maar ook welke acties die waarheid impliceert.

Verificatie en onderhoud

Ground truths vereisen onderhoud. We houden bij:

last_verified: Wanneer iemand heeft bevestigd dat de bewering nog steeds klopt
evidence: Bestanden die de bewering staven (kunnen op bestaan worden gecontroleerd)
source: Waar de waarheid vandaan komt (CLI-inspectie, architectuurreview, post-incident-leren)

Een ground truth met verouderde verificatiedatums of gebroken bewijslinks is een signaal om te onderzoeken. Of de waarheid is nog steeds geldig en heeft herverificatie nodig, of de realiteit is veranderd en de waarheid moet worden bijgewerkt.

Echte voorbeelden uit productie

Beveiligingsgrens

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Deze ground truth voorkomt een klasse van misplaatste “beveiligingsverbeteringen” die het product zouden breken.

Nauwkeurigheid op extractiemoment

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Dit kwam voort uit een pijnlijke ervaring. Agents patchten falende taalpakketten door validator-only filters toe te voegen die de testharness groener lieten ogen, terwijl de live Maguyva-extractor nog altijd de verkeerde edges uitzond. De regel dwingt fixes terug naar het echte pad: YAML-config, queries, of handlers.

Meerlaagse filtering

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Dit voorkomt dat agents filters op de verkeerde plek toevoegen, een veelvoorkomende fout die accuratesse-regressies veroorzaakte.

Integratie met het orchestratiesysteem

Ground truths zijn één laag van een breder contextsysteem:

Architecturale beslissingen (ADR’s) - Leggen vast waarom we aanpak A boven B kozen
Ground Truths - Stellen vast wat op dit moment definitief waar is
Domeinpatronen - Beschrijven hoe je dingen correct doet
Anti-patronen - Beschrijven wat je moet vermijden en waarom

Een agent die in het systeem werkt, heeft toegang tot alle vier. Ground truths bieden het feitelijke anker, terwijl beslissingen de geschiedenis verklaren, patronen de implementatie sturen, en anti-patronen waarschuwen voor valkuilen.

De impact meten

Sinds we ground truths hebben geïntroduceerd, zien we:

Minder “repareer de gehallucineerde fix”-cycli
Zelfverzekerdere agentbeslissingen wanneer feiten duidelijk zijn
Betere PR-reviews omdat verwachtingen expliciet zijn
Kortere onboardingtijd voor nieuwe agents (en mensen)

De investering in het onderhouden van ground truths betaalt zich terug in minder debuggen en helderdere systeemgrenzen.

Aan de slag

Om een ground truth toe te voegen aan jouw systeem:

Maak een ground_truths.yaml aan in de ai_assets/reference/-directory van je package
Definieer metadata en renderconfiguratie
Voeg beweringen toe volgens het schema
Voer uv run orkestra sync uit om documentatie te genereren
Neem het register op in de agentcontextcompositie

Begin met de feiten die de meeste verwarring veroorzaken of de beperkingen die het vaakst worden overtreden. Dat zijn je meest waardevolle ground truths.

Conclusie

AI-agents zullen hallucineren. Dat zit in hun aard. Maar we kunnen omgevingen creëren waarin hallucinatie wordt beperkt, waarin bepaalde feiten niet onderhandelbaar zijn, waarin agents hun aannames kunnen toetsen aan geverifieerde realiteit.

Ground truths zijn geen complete oplossing. Ze vereisen onderhoud. Ze kunnen verouderen. Ze voegen overhead toe aan het ontwikkelproces.

Maar ze bieden iets waardevols: een gedeeld vocabulaire van feiten dat zowel mensen als agents kunnen vertrouwen. In een wereld waarin agents steeds meer deelnemen aan softwareontwikkeling, wordt dat gedeelde fundament essentieel.

Het alternatief is eindeloze cycli van agents die overtuigd fouten maken en mensen die ze corrigeren. Ground truths doorbreken die cyclus door de correcties expliciet en duurzaam te maken.

Jouw agents verdienen te weten wat waar is. Vertel het ze.

Orkestra: AI-agents orkestreren op schaal

Tue, 06 Jan 2026 00:00:00 GMT

Cijfers in deze post weerspiegelen het systeem op het moment van publicatie (januari 2026). Zie onze teampagina voor actuele cijfers.

Toen we begonnen te bouwen met Claude Code, liepen we tegen een probleem aan dat elk team dat AI-codeerassistenten gebruikt vroeg of laat tegenkomt: één agent kan niet alles goed doen.

Je kunt een agent prompten om een databasespecialist te zijn. Of een securityauditor. Of een frontend-engineer. Maar zodra je hem vraagt alle drie tegelijk te zijn, lijdt de kwaliteit. Context verwatert. Instructies conflicteren. De agent wordt een generalist die overal middelmatig in is.

Dus bouwden we Orkestra.

Wat is Orkestra?

Orkestra is een agent-orchestratiesysteem voor Claude Code en vergelijkbare AI-codeertools. Het coördineert meerdere gespecialiseerde agents, elk met eigen expertise, onder één orchestrator die werk routeert naar de juiste specialist.

Zie het als een uitzendbureau voor AI-agents. De orchestrator ontvangt een taak, identificeert welke specialist die moet afhandelen, en delegeert met de juiste context. Zodra het werk klaar is, vloeien resultaten terug naar de orchestrator voor synthese.

De cijfers vertellen het verhaal:

Component	Aantal
Gespecialiseerde agents	46
Herbruikbare skills	466
Identiteitsarchetypes	27
Mindsets	11
Communicatiestijlen	10
Kennisdomeinen	21

Het karaktersysteem: D&D voor agents

Het kerninzicht achter Orkestra is dat agentgedrag ontstaat uit drie combineerbare primitieven:

Identity definieert wat de agent is. Een architect ontwerpt systeemstructuren. Een debugger traceert fouten naar hun grondoorzaak. Een guardian handhaaft compliance- en beveiligingsgrenzen. We hebben 27 identiteitsarchetypes die gemengd kunnen worden.

Mindset definieert hoe de agent denkt. Een analytische mindset onderbouwt beweringen met bewijs en kwantificeert onzekerheid. Een sceptische mindset stelt aannames ter discussie en zoekt weerleggend bewijs. Een verkennende mindset omarmt ambiguïteit en probeert meerdere aanpakken.

Style definieert hoe de agent communiceert. Een technische stijl bevat exacte waarden en verwijst naar specifieke bestanden. Een beknopte stijl snijdt franje weg en begint met het antwoord. Een diplomatieke stijl balanceert eerlijkheid met tact.

Een agent combineert deze primitieven:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Deze compositie creëert een agent die systemen ontwerpt (architect), kennis verbindt over domeinen heen (knowledge-architect), strategische richting bepaalt (strategist), denkt in bewijs en data (analytical), en communiceert zonder franje (concise).

De kracht zit in combinatorische explosie. 27 identities keer 11 mindsets keer 10 styles levert bijna 3.000 mogelijke agentpersoonlijkheden op. Maar je definieert alleen de combinaties die ertoe doen voor jouw werk.

Skills: herbruikbare capaciteitsmodules

Skills zijn de kennis en workflows die agents kunnen aanroepen. Ze volgen een gelaagd systeem gebaseerd op scope:

Tier	Naam	Scope	Voorbeeld
K0	Foundations	Universele methodologie	Test-first-discipline, bewijsgebaseerde afronding
K1	Identities	Rolgebaseerde workflows	CLI-interfacestandaarden, prestatie-playbook
K2	Domains	Domeinspecifieke kennis	Database-migratiepatronen, authenticatievalidatie
K3	Stacks	Technologiespecifiek	Cloudflare-deployment, Supabase-operaties
K4	Project	Alleen deze codebase	Projectspecifieke workflows en conventies

Skills worden lazy-loaded. Een agent ziet skillnamen en -beschrijvingen bij het opstarten, maar de volledige skillinhoud wordt pas geladen wanneer die wordt getriggerd. Dat houdt de context slank terwijl honderden skills toch vindbaar blijven.

Elke skill bevat:

Duidelijke triggervoorwaarden (“Use when migrating database schemas”)
Stap-voor-stap-begeleiding
Toegestane tools voor de workflow
Succescriteria en herstelpaden bij falen

De 466 skills in ons register bestrijken alles van git worktree-isolatie tot webresearchworkflows tot deployment health validation.

Waarom orchestratie ertoe doet

Single-agent-architecturen lopen snel tegen muren aan:

Contextverwatering. Een contextvenster van 200k tokens klinkt groot totdat je databaseschema’s, API-documentatie, testfixtures en domeinkennis laadt. Specialisten kunnen werken met gerichte context.

Instructieconflicten. Een agent vertellen om “grondig maar snel” te zijn en “alles te verifiëren maar niet te over-engineeren” creëert spanning. Specialisten lossen dit op door een duidelijke scope te hebben.

Expertisediepgang. Een generalistische agent weet een beetje over alles. Een gespecialiseerde agent, samengesteld met de juiste identity en skills, kent zijn domein diepgaand.

Orkestra implementeert flat orchestration: één orchestrator coördineert meerdere specialisten. Specialisten kunnen geen subspecialisten spawnen. Dat voorkomt complexiteitsexplosie terwijl parallel werk mogelijk blijft.

De orchestrator heeft toegang tot 2,2 miljoen tokens aan effectieve capaciteit: zijn eigen venster van 200k plus 10 gelijktijdige subagents met elk 200k. Werk dat een enkele agent zou uitputten, verloopt moeiteloos over de vloot.

De renderpipeline

Agentdefinities leven in YAML. Claude Code leest Markdown. Orkestra overbrugt dat gat met een deterministische renderpipeline:

YAML Registries → Jinja Templates → .claude/agents/*.md

Operators bewerken de YAML-bron. Voer orkestra sync uit. Gerenderde Markdown verschijnt in .claude/agents/. Claude Code pikt de wijzigingen op.

Deze scheiding bedient verschillende doelgroepen:

YAML-bron bevat levenscyclusmetadata, tags, validatieregels en deprecation-notities voor tooling
Gerenderde Markdown bevat alleen wat het model nodig heeft: beschrijving, tools, skills en gedragsrichtlijnen

De pipeline stelt identities, mindsets, styles en skills samen tot één coherente prompt. Een architect-analytical-concise-agent krijgt een heel andere systeemprompt dan een debugger-skeptical-technical-agent, zelfs als ze enkele onderliggende skills delen.

Domeinkennis: het vierbestandenpatroon

Elk kennisdomein volgt een consistente structuur:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Deze structuur dient het laden van agentcontext. Een agent die aan authenticatie werkt, laadt authentication/patterns.md voor begeleiding en authentication/anti-patterns.md om bekende valkuilen te vermijden. De bestanden zijn afgestemd op efficiënt contextladen: gefocust genoeg om nuttig te zijn, uitgebreid genoeg om gezaghebbend te zijn.

We onderhouden 21 topleveldomeinen, waaronder analytics, authenticatie, data science, infrastructuur, machine learning, performance, security en meer. Elk domein kan subdomeinen hebben voor fijnere granulariteit.

Values: het besturingssysteem

Alle agents delen een basislaag aan values die bepalen hoe ze opereren:

Eenvoud eerst. Gebruik de eenvoudigste oplossing die werkt. Voeg alleen complexiteit toe wanneer dat gerechtvaardigd is.

Los grondoorzaken op. Bestrijd nooit alleen de symptomen van een fout. Als een pipeline faalt, debug de pipeline. Als een test faalt, repareer de code of de test.

Op bewijs gebaseerd. Label beweringen als “verified” (met benchmarks) of “estimated” (met aannames). Een gedetecteerd patroon staat niet gelijk aan een bevestigd probleem.

Context-economie. MCP-tools kosten 0,1% van de context. Bestanden lezen kost elk 2%. Pas domeinexpertise toe voordat je code gaat verkennen.

Deze values propageren naar elke specialist via de renderpipeline. Een agent kan ze niet omzeilen door compositie.

CLI: het controlevlak

Orkestra wordt geleverd met een CLI voor het beheren van het agent-ecosysteem:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

De CLI is de single source of truth voor welke agents bestaan, welke skills ze hebben, en of het systeem gezond is. Hij draait validatie vóór sync om problemen vroegtijdig op te vangen.

Overwegingen rond open source

We bouwden Orkestra om ons eigen probleem op te lossen: AI-agents op schaal coördineren voor een complexe codebase. De patronen die we ontdekten zijn niet specifiek voor ons domein.

Het karaktercompositiesysteem (identity + mindset + style) is toepasbaar op elk team dat agentpersoonlijkheden definieert.

Het skill-tiersysteem (K0-K4) biedt een mentaal model voor het organiseren van herbruikbare capaciteiten per scope.

Het renderpipelinepatroon (YAML-bron + templates + gegenereerde artefacten) scheidt wat de tooling nodig heeft van wat het model nodig heeft.

Het flat-orchestration-model (één coördinator, veel specialisten) vermijdt complexiteit terwijl het parallellisme mogelijk maakt.

Of Orkestra open source wordt, hangt af van of deze patronen waarde hebben voor anderen die bouwen met Claude Code. Als jij tegen de muren aanloopt die we hebben beschreven, kan deze architectuur helpen.

Wat we hebben geleerd

Het bouwen van Orkestra leerde ons dat orchestratie niet gaat over agents slimmer maken. Het gaat over ze gefocuster maken.

Eén agent met perfecte instructies raakt nog altijd door zijn context heen. Eén agent met alle skills raakt nog altijd in de war over welke toe te passen. Eén agent die probeert alles te zijn, levert overal middelmatige resultaten.

Veertig specialisten, elk uitstekend in hun domein, gecoördineerd door een orchestrator die weet wanneer te delegeren: zo leveren wij op.

De cijfers doen er minder toe dan de architectuur. Je hebt misschien vijf agents nodig, of vijftig. Het principe blijft: compositie boven capaciteit, specialisatie boven generalisatie, coördinatie boven individueel heldendom.

Orkestra vormt de motor achter het agent-ecosysteem van Maguyva, ons code-intelligentieplatform. Wil je meer weten? Neem contact op met het team.