---
title: "Claude Code-subagenten: bouw teams die echt werken"
date: 2026-08-16T11:41:05.113Z
updated: 2026-08-16T11:41:05.118Z
canonical: https://ninokroesen.nl/library/claude-code-subagenten-bouw-teams-die-echt-werken
lang: nl
author: "Nino Kroesen"
---
# Claude Code-subagenten: bouw teams die echt werken
## Wat een subagent eigenlijk is
Bijna alles wat over Claude Code-subagenten geschreven wordt, behandelt dezelfde tien minuten: maak een Markdown-bestand met een naam, een beschrijving en een lijst met tools, en Claude begint er werk aan te geven. Dat deel is echt simpel, en de documentatie dekt het goed af. Waar bijna niemand over schrijft is wat erna komt: wat er gebeurt als je er een stuk of twaalf in een proces verwerkt, ze koppelt en ze wekenlang op echt werk loslaat. Ik draai subagenten in productie. Nachtscripts die issues en pull requests openen in een van mijn repositories, een developmentworkflow met een reviewer per taak, en een handmatig bedraad netwerk van headless agents dat wekenlang mijn onderzoeksloop draait. Deze gids is wat me dat daadwerkelijk heeft geleerd: de bedrading, de teampatronen die hun kosten waard zijn, en het zichtbaarheidsprobleem waar niemand over praat.
Eén eerlijke opmerking vooraf, omdat die verandert hoe je de getallen hier moet lezen. Mijn eigen vergelijking van losse agents tegen agentteams is niet gemeten, het is een oordeel op basis van het draaien van beide. Waar deze gids getallen aanhaalt over teams die singles verslaan, zijn dat andermans experimenten, met bronvermelding, niet de mijne. Wat van mij is, is de bedrading en de oorlogsverhalen.
Het concept dat alles verklaart is isolatie, niet parallellisme. Een subagent draait niet binnen je hoofdgesprek. Hij draait in een eigen contextvenster, leest zelf wat hij nodig heeft en geeft een antwoord terug. Wanneer Claude Code een repo verkent of een wijziging plant, doet een ingebouwde subagent precies dat. Wat isolatie je oplevert: parallel werk dat je hoofdcontext niet vervuilt, een begrensde faalradius, en delegatie die ook echt delegeert. Wat het kost: de agent leest alles opnieuw wat hij nodig heeft, tokens vermenigvuldigen zich, en de kwaliteit van de delegatie zit vrijwel volledig in de beschrijving, want de beschrijving is wat het model gebruikt om te beslissen of het de agent überhaupt inzet.
## Ingebouwde subagenten
Claude Code wordt geleverd met ingebouwde subagenten: Explore, Plan en general-purpose. Je hebt ze gebruikt, zelfs al heb je ze nooit bij naam genoemd. Explore leest de codebase en rapporteert terug, Plan legt een wijziging voor. Ze werken op dezelfde manier als een aangepaste subagent: geïsoleerde context, een rol, een tool-allowlist. De huidige documentatie op [code.claude.com](https://code.claude.com/docs/en/sub-agents) is de referentie voor de volledige veldenlijst, en dit deel van het product verandert snel genoeg dat je die moet raadplegen in plaats van een blogpost te vertrouwen, deze inbegrepen.
## Een aangepaste subagent maken
Een aangepaste subagent is een Markdown-bestand met frontmatter. Het staat in je agents-map, op projectniveau of gebruikersniveau, afhankelijk van waar je het wilt hebben, en de exacte map is tussen releases verplaatst, dus raadpleeg de documentatie in plaats van op je geheugen te vertrouwen. Als de agent langere instructies nodig heeft, zet je die na de frontmatter als de body van het bestand. De meeste nuttige agents bestaan gewoon uit frontmatter:
```
---
name: code-reviewer
description: Reviews diffs for correctness bugs, missing edge cases and secrets. Use after any code change.
tools: Read, Grep, Glob, Bash
---
```
Dat bestand is de agent. De naam is de identifier. De beschrijving is de routeringscue, en die verdient meer zorg dan de rest van het bestand bij elkaar: het is wat het model leest om te beslissen of het de agent überhaupt inzet, dus schrijf het als een functiebeschrijving, niet als een slogan. 'Use after any code change' is specifiek over wanneer. 'Helps with code' is dat niet. De tools-regel is de allowlist: de enige tools die de agent kan aanroepen. Een code-reviewer heeft misschien Read, Grep, Glob en Bash nodig. Een onderzoeker alleen Read en Grep. De documentatie noemt meer opties (een model per agent, permissiemodi, skills, hooks, MCP-servers scopen), maar die twee velden bepalen in de praktijk het meeste.
## Subagenten gebruiken: delegatie en de headless-route
Automatische delegatie gebeurt via de beschrijving: Claude leest die, bepaalt dat de taak past en start de agent. Expliciete delegatie gebeurt wanneer je hem zegt een specifieke agent op een specifiek stuk werk in te zetten. Context wordt niet gedeeld. De subagent leest wat hij nodig heeft uit de repo of uit de input die je doorgeeft, en tools zijn beperkt tot de allowlist. Als een agent Read en Grep heeft maar geen Bash, kan hij geen commando's uitvoeren, en dat is precies de bedoeling.
Het detail dat subagenten van een handigheidje tot infrastructuur maakt, is dat ze je chatsessie helemaal niet nodig hebben. Het `claude -p` headless-commando start er een vanuit een shell met een prompt en krijgt het antwoord terug. Elke agent in mijn netwerk wordt zo geïnstantieerd: `claude -p` met een taak, input aan de ene kant, output aan de andere. Geen chatsessie nodig. Dat is het moment waarop subagenten ophouden een functie van de editor te zijn en procesknooppunten worden die je kunt bedraden.
## Subagenten vs Skills vs Plugins
|
| Subagent | Skill | Plugin |
| :---------- | :---------------------------------------------- | :----------------------------------------------------------------- | :------------------------------------------------------------ |
| Wat het is | Geïsoleerde agent met een rol en tool-allowlist | Een procedure of capaciteit die in de huidige sessie wordt geladen | Een installeerbaar pakket met vooraf gebouwde onderdelen |
| Context | Eigen venster, geeft een resultaat terug | Draait binnen de huidige sessie | Kan subagenten, hooks en meer meeleveren |
| Gebruik bij | Werk heeft isolatie of parallellisme nodig | Claude moet een herhaalbare workflow ter plekke leren | Je wilt vooraf gebouwde onderdelen installeren of verspreiden |
Het zijn geen concurrenten. Een plugin kan subagenten meeleveren, en een subagent kan een skill vooraf laden. De beslissing is simpel: heeft dit werk isolatie nodig (subagent), heeft het een procedure in de huidige loop nodig (skill), of is het iets dat je van elders wilt installeren (plugin)?
## Ze in een netwerk bedraden
Een enkele subagent is een handigheidje. Een netwerk ervan is een proces. Het netwerk dat ik draai is een onderzoeksproces: een begin, een einde, en een loopback binnen het netwerk om een resultaat te itereren. De structuur bestaat uit hardcoded regels met conditionele verbindingen. Elk knooppunt in het netwerk is een agent met een specifieke taak, een input en een output, en de output wordt doorgegeven aan een ander knooppunt, of aan een agentteam, zoals ik een paar knooppunten noem.
De rollen van de knooppunten zijn niet exotisch: factchecken, onderzoek dat de context vergroot die andere agents zullen lezen, code genereren, en review-agents die bovenop de codegeneratoren zitten. Het review-paar krijgt hieronder een eigen sectie. Wat er aan het netwerk zelf toe doet, is de discipline die het afdwingt. Een knooppunt is geen prompt, het is een contract: deze input gaat erin, deze output moet eruit komen, en het volgende knooppunt krijgt ofwel een welgevormd antwoord, ofwel faalt de run zichtbaar. Er zit geen model in de bedrading, dus er is niets om op te improviseren. Ik ontwerp het netwerk zelf en test het. Het netwerk verbetert zichzelf niet, nog niet, en ik weet niet of ik dat wil.
Een netwerk testen betekent de bedrading testen, niet de modellen. De modellen veranderen onder je met elke release; de bedrading is wat van jou is. Bereikt de juiste output het juiste knooppunt? Loopt de loopback daadwerkelijk? Doodt een gefaald knooppunt de run, of geeft het stilletjes rommel door aan het volgende? Die vragen bepalen of het proces je de waarheid vertelt, en het zijn allemaal vragen over je ontwerp. Daarom is dit techniek en niet prompt-gefriemel.
## Agentteams: koppel een criticus aan een schrijver
Het beste patroon dat ik heb gevonden is het adversariële paar. Eén agent schrijft, een tweede agent krijgt de opdracht om te bekritiseren, en de schrijver itereert op de kritiek. In mijn onderzoeksloop is de splitsing ook een kostensplitsing: een goedkoop werkniveau-model genereert, een duur frontier-model weerlegt. De criticus vangt echte defecten die de eigen zelfcheck van de schrijver had goedgekeurd, en een weerlegging vóór de dure stap is de goedkoopste fout die het systeem kan maken. De volledige loop staat in mijn lab-post \[TODO: link het autoresearch-lab-artikel wanneer het gepubliceerd is], dat persoonlijk onderzoek is dat ik in mijn eigen vrije tijd buiten de dagelijkse baan draai; deze gids leent alleen de techniek.
Dat het patroon werkt, is niet alleen mijn gevoel, maar ik wil precies zijn over wat het bewijs zegt. Het multiagent-debatartikel van Du et al. ([arXiv:2305.14325](https://arxiv.org/abs/2305.14325)) bevatte verschillende instanties waarin modellen elkaar over meerdere rondes bevraagden, en de winst was reëel maar ongelijk: bij rekenkundige taken ging de nauwkeurigheid van 67,0 procent bij een enkele agent naar 81,8 procent met debat, en bij GSM8K van 77 naar 85 procent. Hetzelfde artikel vond dat zelfreflectie, een agent die zijn eigen eerdere redenering leest, nauwelijks hielp. De uitwisseling met een andere agent was wat de bal liet rollen. De agent-forest-lijn van werk ([arXiv:2402.05120](https://arxiv.org/abs/2402.05120)) koos de eenvoudigere route, veel agents die stemmen, en haalde een Llama2-13B van 35 procent naar 59 procent op GSM8K, wat beter is dan een enkele Llama2-70B op 54 procent. Een middelgroot model, gedraaid als team, dat een veel groter model dat alleen draait verslaat. Daar mag je even bij stilstaan.
Het ongemakkelijke detail in datzelfde artikel: gewoon stemmen versloeg het fraaiere debatkader in hun vergelijking, 59 tegen 48 procent op hetzelfde model. Dus de eerlijke samenvatting is dat teams helpen, maar hoe ingewikkelder de coördinatie die je bedenkt, hoe onzekerder de winst. Begin met de saaie versie: één schrijver, één criticus, itereren.
De grootschalige versie van hetzelfde idee is het C-compilerexperiment van Anthropic-onderzoeker Nicholas Carlini ([Ars Technica](https://arstechnica.com/ai/2026/02/sixteen-claude-ai-agents-working-together-created-a-new-c-compiler/), [The Register](https://www.theregister.com/software/2026/02/09/claude-opus-46-spends-20k-trying-to-write-a-c-compiler/)): 16 Claude-agents in agent-team-modus, elk in een eigen container, zonder orchestrator, die taken claimen door lockfiles te schrijven. Ongeveer 2.000 sessies in twee weken, zo'n 20.000 dollar aan API-kosten, 100.000 regels Rust, en een compiler die een opstartbare Linux-kernel bouwt en 99 procent van de GCC-torture-suite haalt. De andere getallen uit dat experiment zijn net zo belangrijk: de codekwaliteit was, naar Carlini's eigen zeggen, lang niet op expert-programmeursniveau, en de agents verloren hun samenhang rond de 100.000-regel-grens, waarbij nieuwe functies oude functionaliteit braken. Teams schalen output op, niet oordeelsvermogen.
## Hoe een klein team er in productie uitziet
Je hebt geen compilerexperiment nodig om hier waarde uit te halen. De kleinste versie die ik draai is drie cron-geplande bots in een van mijn repos. Eén bot scant de repository en markeert issues die hij vindt. Een andere bot pakt een gemarkeerd issue op, probeert het te repareren en opent een pull request. Een mens, ik, bepaalt wat er daadwerkelijk gemerged wordt.
Wat die pijplijn me leerde is niet dat de bots goed zijn, maar dat hun outputkwaliteit de dynamiek van het project volgt. Bij een nieuw project waar echt werk te vinden is, worden er echt goede dingen gemarkeerd. Bij een verouderd project dat niet actief ontwikkeld wordt, gaan de bots jagen op heel kleine dingen die het mergen niet echt waard zijn, en de wachtrij vult zich met ruis. Een agentteam versterkt welk signaal het werk al heeft. Dat is geen reden om de bots over te slaan, het is een reden om ze alleen op actief werk te richten en de merge-beslissing menselijk te houden.
## Wat het kost en wanneer je er niet aan moet beginnen
De kosten zijn structureel, en je kunt eromheen plannen in plaats van ze op een factuur te ontdekken.
|
| Enkele subagent | Agentteam (paar) |
| :------------ | :----------------------------------------------------------------- | :------------------------------------------------------------------------ |
| Wat je krijgt | Nieuwe context, parallelle capaciteit | Een criticus die op de output itereert |
| Waar het wint | Begrensde leesintensieve taken, mechanische bewerkingen, onderzoek | Output die scherp moet zijn: code, beweringen, alles wat beoordeeld wordt |
| Wat het kost | Eén extra context aan tokens | Vermenigvuldigde tokens plus een coördinatie-oppervlak |
| Faalmodus | Stille fout in het antwoord, niemand controleert | De reviewfase wordt de bottleneck |
De gemeten versie van de laatste rij komt uit mijn superpowers-forkwerk \[TODO: link het superpowers-artikel wanneer het gepubliceerd is]. Een deel van een build draaide 27 subagent-runs over 11 taken. Eén fix-loop kostte drie commits en drie review-rondes, en die ene taak verorberde ongeveer 22 procent van alle subagent-runs, één taak van de elf. Het productresultaat was goed, rond de 897 tests groen. De proceskosten waren dat niet. Teams maken werk niet gratis, ze verplaatsen het dure deel van het laat fouten vangen naar vroeg reviewers betalen.
De eerlijke wanneer-niet-beginnen-lijst is kort. Als de taak in je eigen contextvenster past, doe het dan zelf. Als de taak triviaal is, is een criticus-paar ceremonie. Als de repo stil ligt, genereren geplande agents ruis in plaats van signaal. En als je het ding niet kunt zien draaien, is dit alles nog niet de moeite waard om te bouwen.
## Prestatie- en beveiligingsoverwegingen
Prestatie is de kostentabel hierboven plus één multiplier: elke subagent leest opnieuw wat hij nodig heeft, dus een taak die over drie agents wordt verdeeld kost meer dan dezelfde taak inline, soms meerdere keren meer. Dat is de prijs van isolatie, en de juiste reactie is niet om subagenten te vermijden, maar om elke agent een taak te geven die groot genoeg is om een nieuwe context waard te zijn.
Beveiliging is vooral allowlist-discipline en hygiëne met betrekking tot derden. Een subagent kan alleen de tools aanroepen die je hem hebt gegeven en de MCP-servers die je hebt gescoped, dus de frontmatter is je beveiligingsgrens. Wanneer je andermans subagent installeert, vertrouw je hun instructies en toolkeuzes. Lees de frontmatter voordat je iets installeert, net zoals je een shellscript zou bekijken voordat je het draait. De grootste community-collectie die ik heb gevonden is [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) op GitHub, 158 plus subagenten in 10 categorieën, installeerbaar als plugins of gekopieerd als losse bestanden.
## Het zichtbaarheidsprobleem
Elke dure fout die ik met agentsystemen heb gemaakt had één ding gemeen: de fout zat de hele tijd in de artefacten, en was volledig onzichtbaar in de proza-output. De samenvatting van een agent vertelt je wat de agent gelooft dat hij deed. Een muur van modeloutput vertelt je wat de loop gelooft dat hij deed. Een netwerk vertelt je wat het deed.
Daarom heeft de onderzoeksloop een live dashboard dat het netwerk tekent terwijl het draait: welke fase wordt uitgevoerd, wat het produceerde, wat faalde. Wanneer een run misgaat, zie je de vorm van de fout voordat je één regel modelvertelling leest, en meestal is de vorm genoeg. Het volledige argument voor zichtbaarheid, met het scorebord, staat in de lab-post \[TODO: zelfde link als boven]; de gidsversie is: bouw de weergave voordat je het systeem vertrouwt. Een handbedraad netwerk is alleen een black box als je de output een muur van tekst laat zijn.
## Veelvoorkomende valkuilen en probleemoplossing
* **De agent wordt nooit geactiveerd**: de beschrijving is te vaag of te breed. Schrijf de exacte trigger: wanneer, waarop, met welk doel.
* **De agent kan de taak niet uitvoeren**: er ontbreekt een tool in de allowlist. Voeg de tool toe, of verdeel de taak anders.
* **Contextkosten lopen op**: elke agent leest opnieuw wat hij nodig heeft. Start geen agent voor iets dat in je eigen contextvenster past.
* **De reviewfase wordt de bottleneck**: elk team voegt een criticus toe, en de criticus kan het traagste onderdeel worden. De 22 procent-fixloop hierboven is hoe dat er in de praktijk uitziet.
* **Stille repo, lawaaierige bots**: geplande agents op inactief werk gaan mierenneuken. Richt automatisering op actieve repos.
* **Je kunt niet zien wat er is gebeurd**: als de enige output proza is, mis je de bug. Bouw de weergave.
## Eerlijke kanttekeningen
Alles wat ik weet over of dit werkt komt uit mijn eigen opstellingen. Geen ander mens heeft mijn netwerk, mijn bots of mijn workflow gebruikt, en ze passen misschien bij niemand anders. Ik heb gemerkt dat teams scherpere output produceren, maar ik heb het niet gemeten, en deze gids zegt dat overal waar het ertoe doet.
Het netwerk verbetert zichzelf niet. Dat is vandaag een beperking en morgen een ontwerpkeuze; als ik ooit agents hun eigen bedrading laat bewerken, verandert de testlast compleet, want dan is wat getest wordt niet langer van mij.
Alles hier over Claude Code-specifieke zaken heeft een halfwaardetijd. De subagenten-documentatie is dit jaar al meerdere keren veranderd, agentteams zijn recent gekomen en zijn nog steeds in beweging, en elk config-blok dat je kopieert zal verouderen. Wanneer iets hier niet meer overeenkomt met wat de tool doet, vertrouw dan de tool.
En het ruisprobleem herhaalt zich overal waar je automatisering toevoegt: bij actief werk vinden mijn bots echte issues, bij stil werk mierenneuken ze. De versterking werkt in beide richtingen, en het is je merge-knop die het eerlijk houdt.
## Waar dit nu staat
De bots draaien nog elke nacht, het netwerk en het dashboard zijn live, en ik bouw de editor rond het netwerk zodat fasen mid-cyclus kunnen worden geïnspecteerd en bijgesteld. Als je nog steeds aan het beslissen bent tussen Claude Code en Cursor, is dat een andere vraag, en de vergelijking die ik schreef in [claude-or-cursor](/library/claude-or-cursor) is waar ik die heb uitgewerkt.
## Begin met één criticus-paar
Als je één ding uit dit alles meeneemt, maak er dan het kleinste team van dat je nog iets leert: één schrijver-agent, één criticus-agent met adversariële instructies, en één mens bij de merge-knop. Bedraad ze zodat je elke overdracht kunt zien, draai ze een week op actief werk, en laat de ruis op stille dagen je vertellen waar de grens van het ding eigenlijk ligt. Het netwerk, het dashboard en de grotere teams zijn allemaal gewoon dat paar, opgeschaald en voorzien van contracten. En de enige gewoonte die ik zou overnemen uit het compilerexperiment is niet de schaal, maar de harness: de waarde zat nooit in de agents, maar in de omgeving die de agents observeerbaar maakte.