Deel C · Module 04
Isoleren: subagents
Wanneer splits je context?
Leerdoelen
Na deze module kun je:
- voorspellen wat een subagent bij de start in zijn context heeft, en wat er na afloop in het hoofdgesprek terechtkomt;
- voor een taak beslissen of hij in het hoofdgesprek hoort of in een subagent, en de kosten van die keuze benoemen;
- een eigen subagent definiëren met een description die tot delegatie leidt, een beperkte tools-lijst en een passend model.
Voorkennis-check
Twee vragen over de loop en het sturen van de agent. Fout? Lees B3 De agentic loop en C1 Sturen eerst terug.
Waar zitten we?
Een subagent is geen nieuw soort primitief, maar een tweede instantie van laag 3: een eigen agentic loop, gestart door de harness (laag 4). Voor het hoofdgesprek is het één tool call (Agent) met één tool_result.
De stof in drie lagen
Kern ± 5 min lezen, daarna twee scenario's vergelijken
Elke tool call in de agentic loop voegt een tool_result toe aan het gesprek, en dat resultaat gaat bij elke volgende request opnieuw mee. Zoekwerk is daardoor duur: vijf bestanden lezen om er één regel in te vinden laat vijf bestanden in je context achter.
Een subagent lost dat op door het werk in een apart contextvenster te doen. Het hoofdgesprek roept de Agent-tool aan met een taakbericht. De subagent draait zijn eigen loop (eigen system prompt, eigen tools, eigen requests) en geeft één eindbericht terug. Alleen dat bericht komt in je gesprek.
Use one when a side task would flood your main conversation with search results, logs, or file contents you won't reference again: the subagent does that work in its own context and returns only the summary.
Vergelijk hieronder dezelfde taak zonder en met subagent. Houd de tellers in de gaten: het hoofdgesprek blijft klein, maar de subagent heeft zelf ook tokens nodig.
Samengevat: een subagent ruilt gedeelde kennis in voor een schoon hoofdgesprek. Hij weet niets van je gesprek behalve wat in het taakbericht staat, en wat hij las is na afloop weg. Dat is precies goed voor zelfstandige zijtaken met veel output, en precies fout voor werk dat heen-en-weer of gedeelde context nodig heeft.
Verdieping wat laadt, ingebouwde agents, eigen agents, delegatie, forks
Wat de subagent bij de start meekrijgt
Each subagent starts with a fresh, isolated context window. It doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read.
Wel
- Zijn eigen system prompt (niet die van Claude Code), plus omgevingsdetails
- Het taakbericht dat het hoofdgesprek schrijft
- Je CLAUDE.md-hiërarchie en een git-status-snapshot (behalve Explore en Plan, of met
omitClaudeMd) - De volledige inhoud van skills in zijn
skills-veld
Niet
- Je gesprek tot nu toe
- Skills die je al aanriep, bestanden die al gelezen zijn
- Je output style en je auto memory
- Het contextvenster van je hoofdmodel: hij krijgt het venster van zijn eigen model
Een regel die de subagent per se moet kennen ("negeer vendor/"), herhaal je dus in het taakbericht. Of zet hem in de system prompt van de subagent.
Ingebouwde subagents
| Agent | Tools | Voor | Bijzonder |
|---|---|---|---|
| Explore | alleen lezen (geen Write/Edit) | code zoeken en begrijpen | start zonder CLAUDE.md en git-status, voor snelheid; diepte quick, medium of very thorough |
| Plan | alleen lezen | onderzoek in plan mode | idem; houdt het hoofdgesprek read-only |
| general-purpose | alle tools | meerstappenwerk met lezen én wijzigen | model van het hoofdgesprek |
Een eigen subagent
Een Markdown-bestand met frontmatter; de body wordt de system prompt. Alleen name en description zijn verplicht. De belangrijkste velden:
| Veld | Doet |
|---|---|
description | wanneer Claude moet delegeren: de routing-key, net als bij skills (C1). "use proactively" moedigt automatische delegatie aan |
tools / disallowedTools | allowlist of denylist; zonder tools erft hij alles |
model | haiku, sonnet, opus, fable, een volledige model-ID of inherit |
permissionMode | bijv. plan voor een strikt lezende agent |
skills | skills die volledig voorgeladen worden |
isolation: worktree | werkt in een eigen git-worktree; wordt opgeruimd als er niets veranderd is |
maxTurns | maximaal aantal turns; daarna komt de output terug als gedeeltelijk |
memory | eigen persistent geheugen (user, project, local) |
Locaties, van hoge naar lage prioriteit bij dezelfde naam: managed settings, de --agents-flag, .claude/agents/ (project), ~/.claude/agents/ (user), plugin. Projectagents commit je, zodat je team ze ook heeft.
Hoe een subagent gekozen wordt
- Automatisch: Claude vergelijkt de taak met de descriptions. Probabilistisch, net als skills.
- Bij naam in je prompt ("gebruik de test-runner"): Claude beslist nog steeds.
- @-mention: garandeert dat die subagent de taak doet.
- Sessiebreed:
claude --agent test-runnerlaat de hele sessie als die agent draaien.
Wanneer niet?
Blijf in het hoofdgesprek als de taak veel heen-en-weer vraagt, als fasen veel context delen (plannen, bouwen en testen van dezelfde wijziging), bij een kleine gerichte wijziging, of als snelheid telt: een gewone subagent begint blanco en moet eerst context verzamelen. En let op bij parallel werk:
When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context, and each subagent spends tokens of its own while it runs.
Nuance: niet (meer) om je venster te redden
Met vensters van 1M tokens en automatische compaction noemen de best practices van Claude Code "gebruik subagents om je contextvenster te beschermen" inmiddels verouderd advies: het venster raakt zelden echt vol. Subagents blijven nuttig voor parallel werk, voor output met veel ruis die je niet wilt zien, en voor een onafhankelijke review. Elk van die drie kost wel extra tokens. En een taak aan een subagent geven maakt het antwoord niet beter: een verse reviewer helpt omdat hij jouw redenering niet zag, en dat is iets anders dan delegeren.
Fork: een subagent die wél alles weet
Een fork erft het hele gesprek: dezelfde system prompt, tools, model en historie. Alleen zijn eigen tool calls blijven buiten je gesprek. Gebruik een fork als een gewone subagent te veel achtergrond zou missen, of om parallel twee aanpakken te proberen. Start er zelf een met /subtask <taak>. Omdat system prompt en tools identiek zijn, deelt een fork de prompt-cache met het hoofdgesprek en is hij goedkoper dan een verse subagent met dezelfde context.
Onder de motorkap Agent-tool, nesting, limieten, achtergrond, hooks
De Agent-tool
Voor het hoofdgesprek is delegeren een gewone tool call. Het eindbericht van de subagent wordt het tool_result:
tool_use in het hoofdgesprek (ingekort)
{ "type": "tool_use", "name": "Agent",
"input": {
"subagent_type": "test-runner",
"description": "Tests draaien en failures rapporteren",
"prompt": "Draai python3 -m unittest -v. Rapporteer per falende test: naam, verwacht vs. kreeg, vermoedelijke oorzaak in winkel/prijs.py. Geen geslaagde tests noemen." } }
De prompt is alles wat de subagent over je taak weet. Een goed taakbericht noemt het doel, wat al bekend is, de grenzen ("niets wijzigen") en de vorm van het antwoord. Een subagent kan alleen zo goed rapporteren als hij gebriefd is.
Limieten
- Nesting: een subagent kan zelf subagents starten, standaard tot drie lagen onder het hoofdgesprek (
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH;1zet nesting uit). Op de diepste laag houdt Claude Code deAgent-tool achter. - Gelijktijdig: standaard 20 lopende subagents per sessie (
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS). Er is geen limiet op het totaal over een sessie. - Descriptions: boven samen 15.000 tokens aan eigen agent-descriptions krijg je een waarschuwing bij de start. Houd descriptions kort en zet details in de system prompt, die alleen laadt als de agent draait.
- Gebruik: de requests van een subagent tellen mee voor dezelfde gebruikslimieten als je hoofdgesprek.
Voorgrond, achtergrond, hervatten
Subagents die Claude vanuit het hoofdgesprek start, draaien standaard op de achtergrond: je kunt doorwerken en het resultaat komt binnen als het klaar is. Een afgeronde subagent kan hervat worden met zijn eigen context intact, bijvoorbeeld om een vervolgvraag te stellen zonder alles opnieuw te laten lezen.
Hooks rond subagents
Er zijn hook-events SubagentStart en SubagentStop; de hook krijgt de agentnaam als agent_type. Een subagent kan ook hooks in zijn eigen frontmatter hebben, die alleen gelden zolang hij draait. Daarmee maak je bijvoorbeeld een database-agent waarvan de Bash-tool alleen SELECT mag (C2). Let op: plugin-subagents negeren hooks, mcpServers en permissionMode in hun frontmatter (C5).
Skills in een subagent laten draaien
Het werkt ook andersom: een skill met context: fork (en optioneel agent: Explore) draait in een eigen subagent in plaats van in je gesprek. Zo combineer je een herbruikbare procedure (skill) met isolatie (subagent).
Uitgewerkt voorbeeld: een test-runner die alleen failures rapporteert
Testoutput is het klassieke voorbeeld van een zijtaak die je gesprek vult: honderden regels "ok", waarvan je alleen de twee failures nodig hebt.
.claude/agents/test-runner.md
---
name: test-runner
description: Draait de testsuite en rapporteert alleen falende tests met oorzaak. Use proactively na codewijzigingen of als de gebruiker vraagt of de tests slagen.
tools: Bash, Read, Grep, Glob
model: haiku
maxTurns: 15
---
Je draait tests en rapporteert, je repareert niets.
1. Draai de testsuite (bv. `python3 -m unittest -v` of `pnpm test`).
2. Lees bij elke falende test de test en de code die hij raakt.
3. Rapporteer per falende test: naam, verwacht vs. kreeg,
vermoedelijke oorzaak met bestand:regel. Maximaal 150 woorden.
Noem geen geslaagde tests.
- description: wat en wanneer, met "use proactively" zodat Claude ook zonder expliciete vraag delegeert na een wijziging.
- tools: geen Edit of Write. De agent kan rapporteren maar niet "even fixen": dat blijft in het hoofdgesprek, waar jij meekijkt.
- model: testoutput lezen vraagt weinig redeneerkracht, dus een sneller en goedkoper model is genoeg. Het zware model houdt de context en doet de fix.
- Vorm van het antwoord: dit eindbericht is het enige dat terugkomt. Hoe strakker de vorm, hoe kleiner en bruikbaarder het
tool_result.
Meet het verschil: tests in je hoofdgesprek of in een subagent
Starter: oefenrepo/c4-subagents/. Een prijsmodule met twee bugs en 45 tests (alleen de Python-standaardbibliotheek), waarvan er twee falen. Je meet met /context hoeveel tokens je hoofdgesprek gebruikt.
Opdracht
- Kopieer de map,
git init && git add -A && git commit -m start, startclaude. Vraag: "Draai python3 -m unittest -v, laat alle uitvoer zien en vertel welke tests falen." Noteer daarna de Messages-regel in/context. /clear. Maak.claude/agents/test-runner.mdzoals in het voorbeeld hierboven. Vraag: "Gebruik de test-runner om te kijken welke tests falen." Noteer/contextopnieuw. Wat staat er nu in je gesprek?- Vraag het hoofdgesprek de twee bugs te repareren op basis van het rapport, en daarna (zonder de subagent te noemen): "Slagen de tests nu?" Delegeert Claude uit zichzelf?
- Maak het kapot. Haal
Bashuit detoolsvan de test-runner en herhaal stap 2. Wat rapporteert hij nu? Zet daarnaBashterug en verander de description in "Helpt met dingen". Delegeert Claude nog uit zichzelf bij stap 3?
Verwacht resultaat
Stap 1 en 2: in stap 1 staat de volledige testoutput als tool_result in je gesprek. In stap 2 staat er alleen een Agent-call met een kort rapport (twee failures: test_afronding_half_up en test_precies_vijftig_euro_gratis, met oorzaak in korting en verzendkosten). Het verschil in Messages-tokens is bij deze kleine suite bescheiden (ongeveer 1k). Bij een echte suite met duizenden regels loopt het snel op.
Stap 3: door "use proactively" en de passende description delegeert Claude meestal zelf aan de test-runner. Meestal, niet altijd: delegatie is net als skill-keuze probabilistisch.
Stap 4: zonder Bash kan de agent de tests niet draaien. Hij leest de tests en code en gaat redeneren, of meldt dat hij niets kan uitvoeren. Een vage description leidt ertoe dat Claude de tests zelf in het hoofdgesprek draait. Dat zie je terug in /context.
Als het niet werkt, kijk naar …
- Agent wordt niet gevonden. Het bestand moet in
.claude/agents/staan, met geldige frontmatter enname/description. Bestond de mapagents/nog niet bij de start van de sessie, herstart dan: Claude Code bewaakt alleen mappen die er al waren. - Veldnaam genegeerd. Veldnamen zijn camelCase en exact (
maxTurns, nietmax_turns). Een onbekend veld wordt stil genegeerd;claude --debugmeldt het in het debuglog. - Tests draaien niet. Draai vanuit de projectroot (
python3 -m unittest -v), niet vanuittests/, anders vindt Python het pakketwinkelniet. - Claude delegeert nooit. Gebruik een @-mention om delegatie af te dwingen, en verbeter daarna de description.