Claude Code subagents veranderen de manier waarop je met AI-assistenten samenwerkt aan code. In plaats van één generieke assistent die alles probeert te doen, krijg je een team van specialisten met elk hun eigen rol, contextvenster en toolset. Het resultaat is een workflow waarin je hoofdsessie een dunne orkestrator wordt die het echte werk delegeert aan experts. Wie het concept goed begrijpt, bouwt binnen een week een setup die zwaar werk aankan.

Wat een Claude Code subagent precies is

Een subagent is verrassend simpel. Het is een markdown-bestand met YAML-frontmatter bovenaan en een systeemprompt eronder. Je plaatst het bestand in .claude/agents/ binnen je project of in ~/.claude/agents/ voor globale beschikbaarheid, en Claude Code ontdekt het bij de volgende sessiestart.

De kracht zit in vier eigenschappen. Elke subagent draait in een eigen geïsoleerd contextvenster, waardoor taakspecifieke details je hoofdgesprek niet vervuilen. Elke subagent krijgt een nauwkeurig afgestemde systeemprompt voor zijn vakgebied, wat de kwaliteit op gespecialiseerde taken sterk verhoogt. Je kunt subagents delen tussen projecten en teamleden, en je bepaalt per agent welke tools beschikbaar zijn. Die laatste laag is een veiligheidsgrens die de schade beperkt als een agent zich misdraagt.

Frontmatter: de zeven knoppen die gedrag sturen

De YAML bovenaan een subagent-bestand bevat een handvol velden, waarvan er twee verplicht zijn: name en description. De rest stelt je in staat om kosten, gedrag en vindbaarheid te tunen.

  • name: de identifier die je gebruikt bij expliciete aanroepen en in /agents. Moet overeenkomen met de bestandsnaam.
  • description: het veld dat bepaalt of de agent automatisch wordt aangeroepen. Hierover meer hieronder.
  • tools: de toegestane tools. Beperk dit altijd. Een reviewer krijgt Read en Grep, geen Write of Bash.
  • model: kies tussen Sonnet als standaard, Opus voor zware redenering zoals architectuurreviews, en Haiku voor snelle classificatietaken.

De keuze van het model is geen detail. Diepe redeneringstaken zoals security-audits of fintech-logica verdienen Opus. Alledaagse codeertaken draaien prima op Sonnet. Documentatiezoekers en afhankelijkheidscheckers gaan vlot op Haiku. Door deze toewijzing bewust te maken hou je je tokenrekening voorspelbaar.

De description bepaalt of je agent ooit draait

Hier verliezen veel mensen hun subagents zonder het door te hebben. Claude Code kiest automatisch welke subagent wordt aangeroepen door de gebruikersintentie te matchen tegen het description-veld van elke beschikbare agent. Een vage beschrijving betekent dat de hoofdsessie het werk gewoon zelf doet en je specialist stilletjes overslaat.

Vier patronen maken je beschrijving effectiever. Begin met MUST BE USED for X als capitalized signaal. Noem expliciet de talen, frameworks en taken die de agent dekt. Vermeld de grens van het gedrag, bijvoorbeeld “read-only, schrijft nooit bestanden”. En houd elke agent gefocust op één taak. Een agent die tegelijk code reviewt, tests schrijft en documentatie genereert verliest het altijd van drie gespecialiseerde collega’s.

Tool-allowlist als veiligheidsmaatregel

Het tools-veld weglaten betekent dat de subagent alle tools van de hoofdsessie erft. Dat is bijna nooit wat je wilt. De blast radius van een misdragende agent is precies de unie van de tools die hij mag aanroepen.

De praktische verdeling die in productie werkt:

  • Code-reviewers en security-auditors: Read, Grep, Glob en eventueel read-only Bash. Ze beschrijven wijzigingen, ze voeren ze niet uit.
  • Test-writers en refactor-architecten: Read, Write, Edit, Glob en Bash. Schrijvers hebben schrijfrechten nodig per definitie, maar koppel ze altijd aan een downstream review-stap.
  • Researchers en documentatiezoekers: WebFetch, WebSearch, Read en Grep. Onderzoekers verzamelen, ze muteren niet.

Subagents kunnen geen andere subagents oproepen. De delegatieboom is maximaal één niveau diep. Houd alle orchestratie in je hoofdsessie en laat elke specialist precies één taak doen.

De vier ankers van een betrouwbare systeemprompt

De markdown onder de frontmatter wordt elke aanroep opnieuw door de agent gelezen. Omdat er geen gedeelde geschiedenis is met je hoofdsessie, moet deze prompt meer werk doen dan een gewone chat-instructie. Vier ankers maken het verschil tussen een agent die elke keer hetzelfde gedrag vertoont en een agent die langzaam afdrijft.

Het eerste anker is rol. Open met “Je bent een senior code-reviewer gespecialiseerd in TypeScript en Next.js” in plaats van een vage rolomschrijving. Het tweede anker is contextontdekking. Vertel de agent waar de waarheid ligt in deze repo, zoals CLAUDE.md, de docs-map of de laatste git diff. Het derde anker is een genummerde werkstroom. Stappen die genummerd staan overleven het geheugengebrek van de agent omdat ze elke aanroep opnieuw worden gelezen. Het vierde anker is een vast output-formaat. Pin de structuur precies vast: drie secties met kritiek, waarschuwingen en suggesties, gevolgd door een eenregelig oordeel.

Een goede systeemprompt voor een code-reviewer is doorgaans dertig tot zestig regels markdown. Langer betekent meestal dat je dingen herhaalt die in CLAUDE.md horen. Korter en de agent gaat improviseren.

Orchestratiepatronen die workflows schalen

Eén subagent is nuttig. Drie of vier subagents in een patroon is sterk. Er zijn drie patronen die vrijwel elke productieworkflow dekken.

Sequentieel is de standaard. Je hoofdsessie roept agent A aan, wacht op het resultaat, geeft de relevante zaken door aan agent B, en zo verder. De klassieke review-test-deploy-keten. Deze gaat trager maar verbruikt minder tokens.

Parallel stuurt meerdere agents tegelijk vanuit de hoofdsessie. Dit werkt zo snel als de traagste agent. De tokenkosten schalen lineair omdat elke agent zijn eigen systeemprompt en context opnieuw inleest. Gebruik dit voor tijdkritische reviews of exploratie, niet als standaard.

Rolgebaseerd is parallel met expliciete persona’s. Stuur dezelfde code naar een security-reviewer, een performance-reviewer en een onderhoudbaarheid-reviewer tegelijkertijd. De orchestrator voegt de oordelen samen tot één verdict.

Een team van minions samenstellen

De community rond Claude Code heeft inmiddels honderden subagent-definities verzameld voor specifieke rollen. Denk aan een backend-developer, een kubernetes-specialist, een postgres-pro, een penetration-tester of een gdpr-ccpa-compliance-expert. Voor vrijwel elke taal en elk framework bestaat een gespecialiseerde agent met passende tools en model-routing.

Een startteam ziet er bijvoorbeeld zo uit. Een architect-specialist die een plan maakt. Een detective-debugger die de oorzaak van fouten opspoort en kleine, gerichte fixes voorstelt. Een code-reviewer die de projectstandaarden uit CLAUDE.md kent. Een QA-engineer die testplannen ontwerpt met UI-validatie en databasechecks. Met deze vier dek je het grootste deel van een softwareontwikkelcyclus af.

Waar de leverage vandaan komt

Wat veel teams onderschatten is hoe snel de hoofdsessie verandert van uitvoerder naar coördinator. Zodra je vijf tot tien goed beschreven subagents hebt, neemt de mens in de lus orchestratiebeslissingen in plaats van code te reviewen. Dat is de agentische ontwikkelworkflow die de meeste teams willen maar weinig daadwerkelijk bouwen.

De waarde zit in beperking, niet in vrijheid

De grootste denkfout bij subagents is dat ze krachtiger zijn naarmate ze meer mogen. Het tegendeel is waar. De discipline om elke agent strikt te begrenzen is uiteindelijk wat hem betrouwbaar maakt voor productiegebruik.