Claude Code subagents: een praktische gids (2026)

Een subagent is een tweede Claude, gelanceerd door je hoofd Claude Code-sessie, die een taak draait in zijn eigen contextvenster en een resultaat teruggeeft. Hij deelt je gesprekshistorie niet. Hij ziet niet de bestanden die je al hebt gelezen of de beslissingen die je al hebt genomen. Hij krijgt een prompt, doet het werk, en geeft terug.

Die isolatie is de hele feature. De parallellisatie, de specialisatie, de aangepaste toolbeperkingen, dat alles vloeit voort uit één feit: een subagent verbrandt zijn eigen contextvenster en alleen het uiteindelijke antwoord komt terug in het jouwe.

We draaien dagelijks tientallen subagents bij het bouwen van SkillProof, meestal voor onderzoeksfan-out en onafhankelijke fixes over de databestanden van de catalogus. Sommige dingen die we hebben geleerd zijn echt nuttig. Een deel hebben we geleerd door toe te kijken hoe een agent overwinning claimde op werk dat het nooit deed. Beide soorten zitten in deze gids.

Wat een subagent eigenlijk is

In Claude Code is de hoofdsessie een loop: lezen, denken, handelen, observeren, herhalen, waarbij elke stap wordt toegevoegd aan één groeiend gesprek. Een subagent is een aparte instantie van diezelfde loop, gestart midden in een sessie, met zijn eigen historie die leeg begint behalve de prompt die je meegeeft.

Wanneer de subagent klaar is, reist niets van zijn tussenwerk terug. Niet de bestanden die het las, niet de commando's die het draaide, niet de doodlopende paden die het verkende. Alleen de tekst die het kiest terug te geven, landt in je hoofdcontext. Las het 40 bestanden om je vraag te beantwoorden, dan betaalt je hoofdsessie voor geen van die 40 leesbeurten. Het betaalt voor één samenvatting.

Daarom worden subagents beschreven als een manier om context te bewaren: niet omdat het werk gratis is (het kost ergens dezelfde tokens), maar omdat de kost wordt gequarantaind in een venster dat wordt weggegooid, in plaats van eentje die je door de rest van de sessie blijft meeslepen.

De afweging volgt daar direct uit. Een subagent die niet weet wat je al hebt geprobeerd, kan je eigen doodlopende paden herhalen, en hij kan geen verduidelijkende vraag stellen halverwege de taak zoals de hoofdloop dat kan, hij heeft óf genoeg in de prompt om verder te gaan, óf hij gokt. Delegatie koopt isolatie en kost gedeeld geheugen. Elke goede subagentprompt is geschreven door iemand die die afweging heeft geïnternaliseerd.

Waarom contextisolatie het punt is

Stel je een hoofdsessie voor twee uur in een refactor: veertig bestanden gelezen, een dozijn tool calls, een ontwerpbeslissing twee keer heroverwogen. Die historie doet echt werk, het maakt de volgende edit coherent, maar het is ook vijftigduizend tokens ballast.

Nu moet je weten hoe één niet-gerelateerd subsysteem retries afhandelt. Lees die bestanden in de hoofdloop en elk ervan wordt permanente bagage, meerijdend in de context voor de rest van de sessie of je het nu weer gebruikt of niet, tot het deel wordt van waarom het model de daadwerkelijke refactor uit het oog verliest. Een subagent laat je de vraag stellen, het antwoord krijgen, en wegwandelen van het lezen. De veertig bestanden die het las, komen nooit in jouw venster. Jij krijgt één paragraaf terug.

Dat is het mechanisme achter elke legitieme subagent-winst in deze gids: onderzoek, parallelle fixes, rumoerige verkenning. Alle zijn eigenlijk dezelfde zet: doe het dure lezen ergens wegwerpbaars, houd de hoofddraad schoon.

Wanneer subagents beter zijn dan in de hoofdloop werken

Onderzoek over veel bestanden. "Hoe stroomt auth door deze codebase" raakt routes, middleware, sessieopslag, en drie configbestanden. Beantwoord het in de hoofdloop en dat alles landt permanent in je context. Een subagent leest dezelfde bestanden, geeft een synthese terug, en het ruwe materiaal verdwijnt ermee.

Parallelle onafhankelijke taken. Vijf componenten hebben allemaal dezelfde prop-hernoeming nodig. Geen van elkaar afhankelijk. Vijf subagents die tegelijk draaien, zijn klaar in ongeveer de tijd die er één kost, zonder gedeelde state om tussen de wijzigingen te coördineren.

Rumoerige verkenning. Grep op een patroon over een grote repo, drie zoekstrategieën proberen voordat er een raak is, bestanden lezen die irrelevant blijken. Dit is precies het werk dat je gequarantaind wilt hebben. Een subagent kan een tijdje ronddwalen en alleen het nuttige deel komt terug.

Een gespecialiseerde persona isoleren. Een codereview-subagent die alleen ooit reviewt, met een smallere toolset en een prompt afgestemd op scepsis, gedraagt zich consistenter dan je hoofdagent midden in de sessie te vragen "wees nu kritisch over je eigen werk."

Wanneer subagents slechter zijn

Strakke iteratieve loops. Een falende test debuggen door één regel te wijzigen, opnieuw draaien, de nieuwe fout lezen, weer een regel wijzigen, vereist de volledige historie van wat je al hebt geprobeerd. Dat aan elke iteratie een verse subagent geven, betekent het hele onderzoek elke keer opnieuw uitleggen, trager en slechter dan in de hoofdloop blijven. Dit is het terrein dat onze systematic debugging-notities behandelen: debuggen wil continuïteit, geen delegatie.

Taken die het volledige gesprek nodig hebben. Heeft de gebruiker tien berichten besteed aan precies verfijnen wat "ruim deze API op" betekent, dan zal een subagent die alleen de laatste instructie ziet, opruimen volgens zijn eigen gok over "schoon," niet de gok die je hebt onderhandeld. Alles waarbij de eisen in het gesprek leven in plaats van in een prompt die je kunt herformuleren, is een slechte fit.

Simpele wijzigingen in één bestand. "Hernoem deze variabele in dit bestand" delegeren aan een subagent voegt een extra rondje toe, een verse contextlading, en een resultaat dat je nog steeds moet lezen en vertrouwen, voor werk dat direct vijftien seconden had gekost. Een geïsoleerde worker opstarten betaalt zich alleen uit als het werk waarvan het je afschermt, echt groot is.

Het patroon door alle drie heen: subagents zijn erger precies wanneer de waarde van gedeelde context zwaarder weegt dan de kost van die meedragen. Isolatie stopt een feature te zijn zodra continuïteit is wat de taak nodig had.

Aangepaste agentdefinities

Claude Code laadt aangepaste subagents uit markdown-bestanden onder .claude/agents/ (projectniveau, gedeeld via git) of ~/.claude/agents/ (persoonlijk, elk project). Elk bestand is één agent: frontmatter plus een systeemprompt, dezelfde vorm als een skill maar met een persona in plaats van een procedure.

Hier is een volledig, geannoteerd voorbeeld, een code-reviewer beperkt tot read-only reviewwerk:

---
name: code-reviewer
description: Reviews a diff or pull request for correctness bugs,
  security issues, and missed edge cases. Use after a change is
  written and before it's committed, not while still drafting.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior engineer doing a pre-commit review. You did not
write this code and you have no attachment to it.

When given a diff or a set of changed files:

1. Read every changed file in full, not just the diff hunks.
   Bugs hide in the context around a change as often as in the
   change itself.
2. Check for: unhandled errors, off-by-one boundaries, null or
   undefined paths the type system doesn't catch, and any
   secret or credential that shouldn't be committed.
3. Do not comment on style or formatting unless it hides a bug.
   A linter's job is not your job.
4. For each finding, cite the file and line, and say what
   breaks and how you'd confirm it. If you're not sure something
   is a bug, say so explicitly instead of stating it as fact.
5. If you find nothing, say that plainly. Do not invent minor
   issues to look thorough.

Never run commands that modify files. You are reviewing, not fixing.

Een paar dingen die hier van belang zijn. De name is hoe je hem aanroept (Use the code-reviewer agent to check this diff) of hoe Claude Code hem automatisch aanroept op een matchende taak. Het description-veld draagt hetzelfde gewicht als in een skill: specifieke triggervoorwaarden verslaan een vage samenvatting.

tools is een echte veiligheidsgrens, geen suggestie. Alleen Read, Grep, Glob, Bash opsommen betekent dat deze agent fysiek Edit of Write niet kan aanroepen, ook al besliste zijn eigen redenering dat een fix voor de hand lag. Dat is bewust: een reviewagent die ook de code kan patchen die hij beoordeelt, is er een die je niet kunt vertrouwen om alleen te reviewen. model laat je een mechanische, goed gespecificeerde agent naar een goedkoper model routeren dan je hoofdsessie, aangezien de taak niet het volle gewicht van je primaire model nodig heeft.

De body is hetzelfde vakmanschap als een skill: negatieve beperkingen ("becommentarieer geen stijl," "verzin geen kleine issues") doen meer werk dan positieve, omdat ze zijn wat een reviewer ervan weerhoudt zijn output op te vullen om grondig te lijken.

Parallelle patronen die echt werken

Fan-out reads. Start meerdere subagents tegelijk, elk toegewezen aan een ander deel van dezelfde vraag: één leest de auth-module, één de datalaag, één de testsuite. Elk geeft een korte synthese terug. Jij krijgt drie antwoorden in de tijd die één sequentiële pass zou kosten, en de ruwe bestandsinhoud raakt je hoofdcontext nooit.

N onafhankelijke fixes. Een batch componenten heeft dezelfde mechanische wijziging nodig, en geen ervan importeert van de ander. Start één subagent per component, elk met een op zichzelf staande prompt: de exacte wijziging, het exacte bestand, de exacte acceptatiecheck. Dit is het schoonste parallelle geval, geen subagent hoeft te weten wat een andere deed.

Beide patronen delen een vereiste die makkelijk over te slaan is en duur wanneer je dat doet: elke prompt moet op zichzelf staan. Hij heeft je gesprek niet. Hangt de taak af van een beslissing gemaakt drie berichten geleden, dan moet die beslissing herhaald worden in de prompt, of de subagent gaat vol vertrouwen het verkeerde doen.

Faalpatronen die we echt hebben meegemaakt

Dit is het deel dat de meeste gidsen overslaan, geschreven door iemand die een subagent twee keer draaide en het werkte. Wij draaien ze dagelijks, en hier is wat er in de praktijk breekt.

Agents die "klaar" rapporteren zonder het werk te doen. Een subagent komt terug met een schone, zelfverzekerde samenvatting: "De drie bestanden bijgewerkt, tests slagen, klaar om te committen." Je checkt, en één bestand is onaangeraakt. Dit is niet het model dat in enige bewuste zin oneerlijk is, het is de teruggegeven samenvatting die afdrijft van wat er echt gebeurde, vooral bij langere taken waarbij het eigen verslag van de agent over zijn werk gecomprimeerd raakt. De fix is saai en niet-onderhandelbaar: verifieer aan de hand van het artefact, niet van het verslag. Lees de diff zelf. Draai de test zelf. Het verslag van een subagent is een bewering, geen bewijs.

Agents die wachten op spookmeldingen. We hebben subagents gehad die midden in een taak pauzeerden, wachtend op een callback of een signaal van een ander proces dat er nooit zou komen, omdat het coördinatiemechanisme alleen bestond in de verbeelding van de prompt, niet in iets daadwerkelijk aangesloten. De fix is nooit een subagentprompt ontwerpen rond een event dat je niet hebt geverifieerd dat het afgaat. Hangt de volgende stap van een subagent af van de output van een andere agent, geef hem dan die output direct mee bij het starten, vraag hem niet een voltooiingssignaal te detecteren dat je niet hebt gebouwd.

Beide faalpatronen leiden terug naar dezelfde discipline: een prompt die niet leunt op gedeelde context of een aangenomen melding is een die een agent daadwerkelijk correct kan afronden, en een uitkomst die je checkt door het bestand te lezen, niet door het verslag van de agent te lezen, is de enige manier om te weten dat het gelukt is. Niets hiervan is een argument tegen subagents. Het is een argument tegen het vertrouwen van een tekstsamenvatting zoals je een diff zou vertrouwen. We draaien ze constant. We mergen alleen niets op hun woord alleen.

Skills werken ook binnen subagents

Een subagent is nog steeds een Claude-instantie, dus hij laadt skills op dezelfde manier als je hoofdsessie: zijn taak matchen tegen geïnstalleerde skillbeschrijvingen en de body binnenhalen bij een trigger. Een codereview-subagent met onze code review checklist-skill geïnstalleerd, krijgt dezelfde gestructureerde pass die hij in de hoofdloop zou krijgen, afgestemd op welke diff je hem ook geeft.

Dit combineert netjes. De subagent regelt waar het werk gebeurt, de skill regelt hoe het gebeurt. Geen van beide hoeft van de ander te weten; ze stapelen automatisch zolang beide geïnstalleerd zijn waar de subagent ze kan zien, projectskills in .claude/skills/, persoonlijke skills in ~/.claude/skills/. Onze beste codingskills-pagina rangschikt de skills die het waard zijn te installeren voordat je een review- of onderzoeksagent opzet.

Subagents vs hooks vs skills

Drie verschillende mechanismen, drie verschillende taken, en ze worden constant door elkaar gehaald:

	Wat het doet	Triggert op	Draait waar
Skill	Leert Claude een procedure of stijl	Claude die jouw verzoek matcht met een beschrijving	Binnen de huidige context
Hook	Draait automatisch een vast shellcommando	Een lifecycle-event (voor een tool call, na een antwoord, sessiestart)	Buiten het model, deterministisch
Subagent	Delegeert een taak aan een geïsoleerde Claude-instantie	Een expliciete aanroep, door jou of door de hoofdagent	Een apart contextvenster

Een skill verandert hoe Claude iets aanpakt dat het toch al gaat doen. Een hook dwingt iets elke keer af, onvoorwaardelijk, zonder het model te vragen het te onthouden: tests draaien na elke edit, een commit blokkeren als er secrets zijn gedetecteerd. Een subagent verandert waar werk gebeurt, verplaatst het naar een wegwerpvenster in plaats van je hoofdvenster. We behandelen hooks in de diepte, inclusief hetzelfde soort littekenweefsel als hierboven, in onze Claude Code hooks-gids.

Ze stapelen. Een teamsetup kan een hook gebruiken om te linten na elke write, een skill om de huisstijl-code te leren, en een subagent om de volledige reviewpass te draaien voor de merge, drie lagen, geen overbodig. Ben je de rest van je setup nog aan het samenstellen, dan loopt onze setupgids voor 2026 door waar elk stuk hoort, en onze tokenkostengids behandelt wat alle drie kosten in rust.

FAQ

Delen subagents mijn hoofdsessie's context?

Nee, en dat is het hele punt. Een subagent begint met een lege historie behalve de prompt die je meegeeft. Niets van je hoofdgesprek gaat automatisch mee, en niets wat de subagent leest of doet, gaat terug behalve de uiteindelijke tekst die het teruggeeft. Heeft het achtergrond uit je gesprek nodig, zet die achtergrond dan in de prompt.

Kunnen subagents parallel draaien?

Ja. Meerdere tegelijk starten is het standaardpatroon voor fan-out-onderzoek en voor onafhankelijke, niet-overlappende fixes. Elk krijgt zijn eigen contextvenster, dus ze verstoren elkaar niet, maar ze kunnen ook niet midden in de taak coördineren tenzij je expliciet de output van de een in de prompt van de ander hebt gestopt.

Hoe weet ik of een subagent echt deed wat hij beweerde?

Check het artefact, niet de samenvatting. Lees de diff, draai de test, open het bestand. We hebben subagents gehad die schoon succes rapporteerden over werk dat gedeeltelijk ongedaan was, niet uit oneerlijkheid maar omdat een samenvatting een reconstructie is, en reconstructies drijven af. Behandel elk subagentverslag als een bewering om te verifiëren.

Waar leven aangepaste agentdefinities?

.claude/agents/*.md voor projectniveau-agents die meereizen met de repo via git, en ~/.claude/agents/*.md voor persoonlijke die beschikbaar zijn in elk project. Elk bestand heeft minimaal name en description nodig in zijn frontmatter; tools en model zijn optioneel maar het waard om bewust in te stellen in plaats van op hun standaard te laten staan.

Moet ik beperken welke tools een subagent kan gebruiken?

Ja, altijd als de agent een smalle taak heeft. Een reviewagent die geen Edit kan aanroepen, kan niet per ongeluk het ding patchen dat hij zou moeten bekritiseren. Een read-only onderzoeksagent die geen Bash kan aanroepen, kan niet per ongeluk iets destructiefs draaien tijdens het rondsnuffelen. Het tools-veld in de frontmatter van een agent is het mechanisme, en het instellen ervan is goedkoper dan debuggen wat een te machtige agent deed met zijn resterende tijd.