Claude Code-subagents: wat ze zijn en hoe je ze gebruikt

Wat een subagent daadwerkelijk is

Wanneer Claude Code een taak tegenkomt die het hoofdgesprek zou overspoelen met output, draagt het die taak over aan een subagent: een afzonderlijke Claude-instantie met een eigen vers contextvenster, een eigen model en een beperkte set tools. Deze voert het werk uit en geeft een kort resultaat terug. Het logbestand van tienduizend regels dat zojuist is uitgelezen, komt nooit in jouw context terecht — alleen de drie regels die er daadwerkelijk toe deden.

Wees precies over wat isolatie inhoudt. Een subagent erft je gespreksgeschiedenis of de bestanden die Claude al heeft gelezen niet over — hij begint met een schone lei. De initiële context is een bewust klein pakket: de eigen systeemprompt (de configuratie-instructies, niet de volledige Claude Code-systeemprompt), het delegatiebericht dat de subagent heeft gestart, je CLAUDE.md-projectgeheugen, een git status-snapshot en eventuele skills die je hebt gekoppeld. Alleen de uiteindelijke samenvatting keert terug; de ruwe resultaten en opgehaalde pagina's blijven achter.

Dat eenrichtingsventiel houdt het hoofdgesprek klein, wat het sneller en goedkoper houdt, omdat elk bericht in Claude Code het volledige gesprek opnieuw verzendt. Een turn wordt geprijsd op de gehele transcriptie, niet alleen op je laatste instructie, dus een context die is opgeblazen met log-output kost meer bij elke daaropvolgende turn — dezelfde logica achter prompt caching en context-hygiëne. Eén uitzondering: een fork erft het volledige gesprek over in plaats van schoon te beginnen, terwijl een benoemde subagent wel schoon begint.

Wanneer je een subagent inzet

Subagents bewijzen hun waarde wanneer een bewerking omvangrijk, repetitief of verkennend is — werk waarvan je niet de volledige output nodig hebt, maar alleen de conclusie.

Het patroon: delegeer de stap met veel volume, behoud de beslissing in de hoofdsessie. Als je merkt dat je langs tool-output scrolt die je toch nooit gaat lezen, hoorde dat werk thuis in een subagent — en als je de volledige output voor je neus nodig hebt om te beslissen, houd het dan in de hoofdthread.

Hoe je er een configureert

Een subagent is een klein Markdown-bestand: YAML-frontmatter bovenaan, een systeemprompt in de body. Alleen de naam en beschrijving zijn verplicht; de beschrijving is wat Claude Code gebruikt om te bepalen wanneer de subagent moet worden aangeroepen, dus maak deze specifiek. Twee optionele velden, tools en model, bieden de daadwerkelijke controle.

De velden die er toe doen:

Waar je het bestand neerzet, bepaalt wie er toegang toe krijgt. Een bestand in .claude/agents/ hoort bij het project en reist mee in versiebeheer, zodat het hele team het erft; een bestand in ~/.claude/agents/ is persoonlijk en volgt jou over verschillende projecten. Bij naamsconflicten wint het meer specifieke bereik, en door de organisatie beheerde instellingen overschrijven beide — het mechanisme dat een platformteam gebruikt om te standaardiseren over een hele vloot.

Claude Code roept een subagent automatisch aan wanneer je verzoek voldoende overeenkomt met de beschrijving — wat de reden is dat een strakke, taakspecifieke beschrijving beter werkt dan een slimme naam — of expliciet, wanneer je deze bij naam noemt of @-t. Voer /agents uit om ze te bekijken en te bewerken, of claude --agent <name> om een hele sessie als zodanig uit te voeren.

Het expliciet instellen van het model is geen administratieve bijzaak — het is de sleutel tot kostenbeheersing. Een test-runner die op Opus staat ingesteld, kost voor dezelfde output ongeveer 40x zoveel als een Haiku-variant en voert de taak niet beter uit. Claude Code bepaalt de volgorde als volgt — een override per aanroep, het frontmatter-model, de omgevingsvariabele CLAUDE_CODE_SUBAGENT_MODEL en vervolgens het model van je sessie — dus een niet-ingesteld model betekent dat de subagent draait op het model dat je op dat moment gebruikt. Voor informatie over welk model bij welke taak past, zie Opus vs Sonnet vs Haiku: a cost-vs-capability routing guide.

Vier subagent-patronen die het kopiëren waard zijn

De meest nuttige subagents vallen uiteen in vier vormen, elk met een duidelijk passend model:

• Test runner (Haiku). Voert de suite uit, retourneert alleen de mislukte gevallen en de eerste foutregel van elk. Heeft Bash en Read nodig — veel volume, nul redeneervermogen, de typische taak voor Haiku.
• Code reviewer (Sonnet). Leest een diff en markeert kwaliteits-, beveiligings- en correctheidsproblemen. Geef het Read, Glob en Grep, maar geen schrijftoegang — het mag geen code wijzigen tijdens de review.
• Doc fetcher (Haiku of Sonnet). Haalt documentatie of API-referenties op en retourneert de twee alinea's die de vraag beantwoorden. De volledige pagina's zijn ruis; deze buiten de hoofdthread houden is de echte winst.
• Migration worker (Sonnet). Past een mechanische wijziging toe over vele bestanden — een dependency-bump, een import-rewrite, een framework-upgrade. Je wilt de samenvatting van wat er is gewijzigd en wat er kapot is gegaan, niet elk afzonderlijk fragment.

Het patroon herhaalt zich: een beperkte toolset, een expliciet model en een prompt die net zo goed vermeldt wat er niet moet worden geretourneerd als wat wel.

Subagents, skills en MCP — wat is wat

Subagents zijn een van de drie manieren om Claude Code uit te breiden, en ze worden snel door elkaar gehaald. Een subagent is een afzonderlijke context die werk uitvoert en verslag uitbrengt; een skill is een verpakte set instructies die op aanvraag in de huidige context wordt geladen; een MCP server is een externe tool of databron die Claude aanroept.

De regel: kies voor een subagent wanneer het probleem volume of isolatie is, een skill wanneer het gaat om herhaalbare kennis, en MCP wanneer het gaat om toegang tot een systeem. Ze kunnen worden gecombineerd — een migratie-subagent kan een skill laden en een MCP server aanroepen binnen zijn eigen context. Voor het beheerperspectief, zie tool vs skill vs subagent governance en Claude Skills.

Voorgrond, achtergrond en agent-teams

Een subagent kan op de voorgrond draaien — waarbij je wacht op het resultaat — of op de achtergrond terwijl je doorwerkt. In beide gevallen erft een subagent zonder ingesteld model het model van je sessie over — de stille manier waarop een Opus-sessie elke subagent verandert in een Opus-subagent. Stel het model expliciet in voor de subagents die dit niet nodig hebben.

Agent-teams gaan nog een stap verder: meerdere Claude Code-instanties parallel, elk met een eigen contextvenster. Ze zijn krachtig voor echt parallel werk, maar tevens het duurste wat je kunt doen — in plan-modus verbruikt een team ongeveer 7x de tokens van een standaard sessie, omdat elk teamlid een eigen volledige context onderhoudt en opnieuw verzendt. Houd teams klein, houd elke taak afgebakend en sluit ze af wanneer het werk klaar is. Dit is ook waar governance het meest kritiek is (tool vs skill vs subagent governance).

Wil je het verbruik van subagents en agent-teams per ontwikkelaar inzien, in plaats van verborgen op één grote factuur?

TrueFoundry AI Gateway

Wat subagents kosten

De verzoeken van een subagent maken gebruik van je totale verbruik, net als het hoofdgesprek — isolatie bespaart tokens op de hoofdthread, maar maakt de subagent niet gratis. De besparing komt uit twee hoeken: een goedkoper model dan je sessie anders zou gebruiken, en omvangrijke output die niet bij elke turn opnieuw wordt verzonden.

Het verschil tussen modellen is groot: volgens gepubliceerde API-tarieven is Haiku een orde van grootte goedkoper per token dan Sonnet, wat zelf weer een fractie kost van Opus bij output — dus dezelfde test-runner-taak kan een factor 40 schelen door één regel configuratie. Prompt caching versterkt dit: de gecachte systeemprompt en het projectgeheugen van een subagent worden uitgelezen tegen ongeveer een tiende van de kosten van nieuwe invoer (the prompt-caching cost math). Voor een hele organisatie ontbreekt vaak het inzicht, wat een gateway toevoegt (cost tracking for Claude Code).

Een praktijkvoorbeeld

Een backend-team houdt een hoofdsessie op Sonnet en voegt drie subagents toe: een test-runner en een log-triage op Haiku, en een codebase-explorer op Sonnet. De hoofdsessie blijft overzichtelijk — deze vraagt de test-runner om de suite uit te voeren, ontvangt alleen de vier fouten terug en lost deze op. De kosten dalen omdat het omvangrijke werk op Haiku draait en de hoofdcontext nooit opzwelt. De configuraties staan in .claude/agents/, gecommit naar de repository, zodat elke engineer ze overneemt.

De eerlijke beperking: subagents houden jouw context schoon, maar beheren zichzelf niet. Welke modellen ze aanroepen, wat ze uitgeven en welke tools ze aanraken zijn beslissingen voor de gehele vloot die thuishoren op gateway-niveau, niet in een configuratie op een laptop (Claude Code governance with an AI gateway).

Het beheren en toewijzen van subagent-uitgaven

Een subagent-configuratie is een instelling per ontwikkelaar. Niets in .claude/agents/ weerhoudt een engineer ervan om een subagent naar Opus te laten wijzen of een team van vijf leden te starten. Op één laptop is dat prima; over honderd engineers heen is het een onbeheerde, niet-toegewezen kostenpost — en omdat elk hun eigen context draait, is hun tokenvolume het deel van de rekening dat het snelst groeit en het minst transparant is.

Standaard facturering lost dit niet op. Wanneer Claude Code draait op een ruwe API-sleutel, of bij een cloudprovider zoals Amazon Bedrock, Google Vertex of Microsoft Foundry, worden de kosten per token gefactureerd op je cloudaccount en bieden de dashboards van Anthropic hierin geen inzicht — waardoor het verbruik op één grote hoop belandt zonder uitsplitsing per ontwikkelaar. Toewijzing van kosten moet ergens anders vandaan komen: OpenTelemetry-instrumentatie of een LLM-gateway voor elk verzoek.

Het routeren van Claude Code via de TrueFoundry AI Gateway plaatst één control plane in dat pad. Elk verzoek — hoofdsessie, subagent of teamlid — wordt herleid naar een ontwikkelaar en een sleutel, zodat uitgaven toegewezen zichtbaar worden in plaats van op één hoop gegooid. Je stelt in welke modellen bereikbaar zijn (Haiku en Sonnet voor subagents, Opus voor goedgekeurde situaties), past uitgavenlimieten toe per ontwikkelaar en per team, en meet het verbruik over meerdere providers in één overzicht. De gateway voegt slechts enkele milliseconden per aanroep toe en voldoet aan OpenTelemetry, waardoor governance geen extra latency kost (centralising cost control and observability for AI coding IDEs).

Belangrijke valkuilen

• Een niet-ingesteld model is een overgenomen model. Een subagent zonder ingesteld model draait op het model van je sessie — een dure verrassing bij een Opus-sessie. Stel het expliciet in, of zet een standaard vast met CLAUDE_CODE_SUBAGENT_MODEL.
• Agent-teams verbruiken ~7x zoveel tokens. Zie ze als een hele bewuste keuze voor parallel werk, niet als de standaard instelling.
• Spawn-prompts vormen context. Alles in de prompt wordt vanaf het begin geladen in het teamlid, bovenop CLAUDE.md, skills en MCP servers — houd het dus beknopt.
• Geef elke subagent alleen de tools die nodig zijn. Een test-runner heeft geen schrijftoegang nodig; tools op basis van least-privilege beperken zowel de impact bij fouten als de contextgrootte.
• Een vage beschrijving wordt nooit geactiveerd — of juist overal. Automatische delegatie baseert zich op de beschrijving, dus schrijf deze als een duidelijke routingregel.
• Subagents zijn niet gratis. Hun verzoeken tellen mee voor je verbruik; isolatie bespaart de hoofdthread, niet de subagent zelf.

Gerelateerde artikelen

• Tool vs Skill vs Subagent Governance — waar elk onderdeel thuishoort en hoe je het beheert
• Cost Tracking Claude Code with the TrueFoundry AI Gateway — kostentoewijzing voor subagents en teams
• Opus vs Sonnet vs Haiku: a Cost-vs-Capability Routing Guide — welk model voor welke subagent
• Claude Code Governance with an AI Gateway — controle over modellen, tools en uitgaven op organisatie-schaal
• Claude Skills — de andere manier om Claude Code gerichte functionaliteit te geven

Conclusie

Claude Code-subagents zijn een eenvoudig concept met een groot effect: draag het omvangrijke werk over aan een tweede instantie, behoud de besluitvorming in de hoofdthread, en je sessie blijft snel en goedkoop. De enkele instelling die bepaalt of ze geld besparen of ongemerkt geld kosten, is het model — stel het in op elke subagent, en bewaar Opus en teams voor werk dat die investering waard is.

Dat is het verhaal voor de individuele ontwikkelaar. Het verhaal voor de gehele organisatie is governance: welke modellen subagents mogen bereiken, wat ze mogen uitgeven, welke tools ze mogen aanraken — beslissingen die thuishoren bij de gateway, niet in een configuratie op elke afzonderlijke laptop.

Plaats je coding agents, subagents en alles daartussenin achter één controle- en kostenplatform.

Boek een demo