Subagents gebruiken in Claude Code

Lange zoekacties en rommelige testuitvoer vullen je gesprek in Claude Code snel op. Subagents nemen dat werk mee naar een aparte context en geven een samenvatting terug. Deze handleiding legt uit wat ze zijn, hoe je je eigen maakt en wanneer ze de moeite waard zijn.

Bijgewerkt 30 oktober 2026

Kort antwoord: een subagent is een gespecialiseerde helper waaraan Claude Code een taak overdraagt. Hij werkt in zijn eigen contextvenster met eigen instructies en toegang tot tools, en geeft alleen een resultaat terug. Om er een te maken, sla je een Markdown-bestand met een name en description in de frontmatter op in .claude/agents/ (één project) of ~/.claude/agents/ (alle projecten), en vraag je Claude hem op naam te gebruiken of kies je hem met @.

De details hieronder komen uit de documentatie van Anthropic over Claude Code van oktober 2026. Claude Code verandert vaak, dus voer claude update uit als iets wat hier staat ontbreekt.

Wat subagents zijn

Komt Claude een taak tegen die past bij de beschrijving van een subagent, dan kan het die taak delegeren. De subagent begint blanco: hij ziet je gesprek niet, alleen de instructies die Claude meegeeft. Hij doet zijn werk, zoals tientallen bestanden lezen of een testsuite draaien, en stuurt een samenvatting terug. Je hoofdgesprek blijft kort.

Claude Code heeft ingebouwde subagents, waaronder:

Explore: snel zoeken en analyseren in een codebase, alleen-lezen.
Plan: onderzoek, alleen-lezen, terwijl je in plan mode zit.
General-purpose: taken met meerdere stappen waarvoor zowel verkennen als dingen wijzigen nodig is.

Die hoef je niet in te stellen; Claude gebruikt ze als ze passen.

Je eigen subagent maken

Bepaal het bereik. Voor een subagent die het hele team in één repository kan gebruiken, maak je de map .claude/agents/ in het project. Voor een subagent die je in al je projecten volgt, gebruik je ~/.claude/agents/.
Maak in die map een Markdown-bestand, bijvoorbeeld code-reviewer.md.
Begin het bestand met frontmatter tussen twee regels ---. De eerste regel van het bestand moet --- zijn.
Voeg de twee verplichte velden toe: name (een unieke naam, bijvoorbeeld code-reviewer, zonder dubbele punt) en description (wanneer Claude hem moet gebruiken, bijvoorbeeld Reviews code for quality and best practices. Use after code changes.).
Voeg eventueel tools toe om te beperken wat hij mag gebruiken, bijvoorbeeld Read, Glob, Grep voor een reviewer die alleen leest, en model (een modelalias zoals sonnet of haiku, een volledige model-ID of inherit).
Schrijf onder de afsluitende --- de instructies voor de subagent in gewone taal: zijn rol, wat hij moet controleren en wat hij moet teruggeven.
Sla het bestand op. Claude Code pikt wijzigingen in een bestaande agents-map binnen enkele seconden op; heb je de map tijdens de sessie gemaakt, start Claude Code dan opnieuw.

Je kunt Claude in een sessie ook gewoon vragen een subagent voor je te maken. In huidige versies verwijst het commando /agents je precies daarnaar, of naar het rechtstreeks bewerken van de mappen.

Een subagent gebruiken

Laat Claude kiezen: Claude vergelijkt je verzoek met de description van elke subagent. Woorden als "use proactively" in de beschrijving moedigen het aan om te delegeren.
Vraag op naam: bijvoorbeeld Gebruik de subagent code-reviewer om mijn recente wijzigingen te controleren.
Noem hem: typ @ en kies de subagent. Zo weet je zeker dat die subagent de taak uitvoert.
Voor een hele sessie: voer claude --agent code-reviewer uit.

Wanneer subagents helpen, en wanneer niet

De richtlijnen van Anthropic komen hierop neer:

Gebruik een subagent als	Blijf in het hoofdgesprek als
De taak veel uitvoer oplevert die je niet hoeft te bewaren, zoals logs of zoekresultaten	Je vaak heen en weer moet overleggen
Je wilt beperken welke tools gebruikt mogen worden	Meerdere stappen veel context delen
Het werk op zichzelf staat en kan eindigen in een samenvatting	Het een snelle, gerichte wijziging is
Je onafhankelijk onderzoek parallel wilt laten lopen

Goed om te weten

Hebben twee subagents dezelfde naam, dan wint de locatie met de hoogste prioriteit: beheerde instellingen, dan de optie --agents, dan de projectmap, dan je gebruikersmap, dan plugins.
Een subagent ziet je chatgeschiedenis en de bestanden die Claude al heeft gelezen niet, dus hij is afhankelijk van de instructies die Claude hem geeft.
Standaard kunnen er tot 20 subagents tegelijk draaien.
Veldnamen zijn in camelCase (bijvoorbeeld disallowedTools, maxTurns), en onbekende velden worden stilzwijgend genegeerd, dus controleer de spelling.
Subagentbestanden van een project kun je committen, zodat het hele team dezelfde helpers krijgt.

Als het niet werkt

Claude vindt de nieuwe subagent niet: bestond de agents-map nog niet toen de sessie begon, start Claude Code dan opnieuw.
Het bestand wordt stilzwijgend overgeslagen: veelvoorkomende oorzaken zijn een ontbrekende name of description, ongeldige YAML, of --- dat niet op de eerste regel staat. Voer claude --debug uit en lees het debuglog, of voer claude plugin validate .claude/agents uit om bestanden te vinden waarvan de frontmatter niet te parseren is.
Claude meldt een fout over tools die niet gevonden worden: komt geen enkele vermelding in tools overeen met een echte tool, dan start Claude Code de subagent meestal niet. Corrigeer de spelling van de toolnamen.
Verkeerd model: voer /tasks uit om te zien welk model elke subagent echt gebruikt.

Bewaar de resultaten, niet alleen de samenvatting

Het verslag van een subagent komt in je sessie terecht, en dat is uit beeld zodra de sessie sluit. Met de Workbranch-plugin voor Claude Code zeg je "save this to Workbranch" en worden de taken, beslissingen en open vragen uit de sessie vastgelegd in een project, en de volgende sessie in die map begint met wat er nog openstaat. Zie Workbranch voor Claude. Had een sessie geen ruimte meer, dan lees je in een sessie van Claude Code hervatten hoe je weer verdergaat.

Bronnen

Use Claude Code with your Pro or Max plan (Claude Help Center, gecontroleerd op 30 oktober 2026)
Create custom subagents (Claude Code docs, gecontroleerd op 30 oktober 2026)

Veelgestelde vragen

Kosten subagents extra gebruik?

Verzoeken van subagents tellen mee voor dezelfde gebruikslimieten als je hoofdgesprek. Eenvoudig werk via het veld model naar een goedkoper model zoals Haiku sturen, kan de kosten drukken.

Kan een subagent zijn eigen subagents starten?

Ja, standaard tot drie niveaus onder het hoofdgesprek. Wil je één bepaalde subagent dat beletten, laat Agent dan weg uit zijn lijst met tools.

Kan ik een hele sessie als subagent draaien?

Ja. Start Claude Code met claude --agent gevolgd door de naam van de subagent, en de sessie gebruikt de prompt, tools en het model van die subagent.