Claude subagents: zo maak je ze, stap voor stap

Wat heb je nodig

Wat heb je nodig voor Claude Code subagents?

Subagents zijn onderdeel van Claude Code zelf. Je installeert niets extra en je betaalt er niet apart voor, maar elke subagent stuurt wel eigen verzoeken naar Claude, en die tellen mee in dezelfde gebruikslimieten als je gewone gesprek. Heb je Claude Code nog niet draaien, begin dan bij Claude Code installeren. Welk plan je nodig hebt, staat bij de Claude-abonnementen.

Twee mappen, twee doelen

.claude/agents/ in je projectmap geldt alleen voor dat project. Je commit de map mee in git, zodat iedereen in het team dezelfde subagents krijgt. ~/.claude/agents/ in je gebruikersmap geldt voor al je projecten, alleen op jouw computer; de tilde staat voor je gebruikersmap, op Windows bijvoorbeeld C:\Users\jouwnaam. Hebben twee subagents dezelfde naam, dan wint de projectversie van de persoonlijke. Daarnaast kunnen subagents uit een plugin komen of centraal door je organisatie worden uitgerold; die van de organisatie winnen altijd.

Op 29 oktober 2026

De nieuwste versie van Claude Code is 2.1.312; het stable-kanaal staat op 2.1.308. Alles op deze pagina werkt op beide.

Hoe het werkt

Hoe werkt een subagent in Claude Code?

Een subagent is een aparte Claude-assistent met een eigen contextvenster, een eigen instructie en eigen toolrechten. Je hoofdgesprek geeft hem een taak, hij doet het werk ergens anders en stuurt alleen zijn samenvatting terug. Daar zit de winst: de honderd bestanden die hij las of de duizend regels testuitvoer belanden niet in jouw gesprek, dus je kunt langer doorwerken voordat je gesprek vol raakt. Claude Code heeft er een paar ingebouwd, die je zonder iets te doen al gebruikt.

Wat een subagent wel en niet meekrijgt

Een gewone subagent begint leeg. Hij ziet je gesprek niet, niet de bestanden die Claude al las en niet je eerdere afspraken. Claude schrijft voor hem een opdrachtbericht, en daar werkt hij mee. Wel krijgt hij zijn eigen instructie (de tekst onder de frontmatter), je CLAUDE.md-bestanden, een momentopname van je git-status en de skills die je in zijn definitie noemt. Explore en Plan slaan CLAUDE.md en de git-status over, zodat ze snel en goedkoop blijven. Je output style en het automatische geheugen van je hoofdgesprek komen niet mee. De uitzondering is een fork: die erft het hele gesprek. Daarover gaat Fork of gewone subagent.

Zo kiest Claude een subagent

Claude leest bij elke taak de naam en de description van al je subagents, en kiest op basis daarvan of hij delegeert en aan wie. De description is dus geen etiket voor jou, maar een instructie voor Claude. Wil je dat Claude een subagent uit zichzelf vaker inzet, zet er dan iets in als Gebruik proactief na elke wijziging. Houd de beschrijvingen kort: ze staan altijd in je context. Boven de 15.000 tokens voor al je eigen subagents samen toont Claude Code bij het opstarten een waarschuwing.

Drie manieren om hem zelf aan te roepen

In gewone taal: "Gebruik de reviewer-subagent om mijn wijzigingen na te lopen". Claude beslist dan nog zelf, maar volgt je meestal. Met een @-mention: typ @, kies de subagent uit de lijst en typ je opdracht erachter, bijvoorbeeld @"reviewer (agent)" kijk naar de inlogcode. Dan draait precies die subagent. Of je start de hele sessie als die subagent met claude --agent reviewer; dan neemt je hoofdgesprek zijn instructie, tools en model over.

Eerste subagent

Je eerste Claude Code subagent maken: een reviewer

Je begint met een subagent die niets kan breken: een reviewer die je wijzigingen naleest en een lijstje teruggeeft. Je zet hem in de projectmap, zodat je hem later met je team kunt delen. De inhoud van het bestand staat bij voorbeeld 1.

Of laat Claude het bestand schrijven

Dit is wat Anthropic zelf als snelste route noemt. Plak in Claude Code bijvoorbeeld:

Maak in .claude/agents/ een subagent "reviewer" die mijn laatste wijzigingen naleest op fouten, veiligheid en leesbaarheid. Hij mag alleen lezen en git-commando's draaien, niets aanpassen. Rapport in het Nederlands, in drie groepen: moet opgelost, zou beter zijn, ter overweging.

Open daarna het bestand en lees de frontmatter na: staat er een tools-regel, en staan Edit en Write er niet in? Een subagent die Claude voor je schrijft, is net zo goed als de controle die jij erop doet.

Wat /agents nog doet

Tot versie 2.1.197 opende /agents een menu met tabbladen om subagents te maken en te bewerken. Sinds versie 2.1.198 toont het alleen nog een herinnering: vraag het Claude, of bewerk de bestanden in .claude/agents/ en ~/.claude/agents/ zelf. Kom je in een video of blog dat menu tegen, dan is die uitleg verouderd. De bestanden en velden zijn niet veranderd.

In VS Code en de desktop-app

Je subagents werken daar ook, want ze lezen dezelfde mappen. In de VS Code-extensie verschijnt onder het invoervak een teller als 2 agents zodra er subagents draaien; klik erop voor een boomweergave met status, tijd en tokens per subagent. In de desktop-app opent je achtergrondwerk via Background tasks in het ⋮-menu bovenin. Hoe je Claude Code in VS Code inricht, lees je in Claude Code in VS Code.

Velden

Welke velden zet je in de frontmatter van een subagent?

De frontmatter is het blok tussen de twee regels met --- bovenaan het bestand. Alleen name en description zijn verplicht. Alles onder het tweede --- is de instructie van de subagent: de enige systeemprompt die hij krijgt, zonder de standaardinstructies van Claude Code. Hieronder de velden die je als beginner nodig hebt; de volledige lijst staat bij de agentvelden in Claude Code commands.

Schrijf de description voor Claude, niet voor jezelf

"Reviewt code" is te vaag: Claude weet dan niet wanneer wel en wanneer niet. Beter: Leest de laatste wijzigingen na op fouten en veiligheid. Gebruik na een afgeronde wijziging, voor een commit. Past zelf niets aan. Zo staat er wat hij doet, wanneer hij moet draaien en wat hij niet doet. Werkt een subagent niet zoals je hoopt, dan is de description bijna altijd de plek waar je moet beginnen. Details over de werkwijze horen in de instructie onder de frontmatter; die wordt pas geladen als de subagent draait en kost dus geen context in je hoofdgesprek.

Welk model krijgt je subagent?

Claude Code kiest in deze volgorde: eerst een model dat Claude bij het aanroepen meegeeft, dan het model-veld uit je bestand, dan de omgevingsvariabele CLAUDE_CODE_SUBAGENT_MODEL als je die gezet hebt, en anders het model van je gesprek. Voor zoek- en testwerk is haiku vaak genoeg en zuiniger. Voor beoordelen, zoals een review, kies je inherit of sonnet. Welk model je subagent echt gebruikt, zie je in /tasks. Wat de modellen kosten, staat bij Claude Code kosten.

Spelfouten worden niet gemeld

Velden met twee woorden schrijf je aan elkaar met een hoofdletter in het midden: maxTurns, disallowedTools. Een veld dat Claude Code niet herkent, zoals max_turns, negeert hij zonder foutmelding. Twijfel je, start dan claude --debug en zoek in het logbestand onder ~/.claude/debug naar does not recognize or apply. Een tikfout in de tools-lijst valt wel op: dan weigert Claude Code de subagent te starten, zie de probleemtabel.

Achtergrond betekent minder tools

Subagents draaien standaard op de achtergrond, zodat jij door kunt werken. Een subagent op de achtergrond houdt al zijn MCP-tools, maar van de ingebouwde tools alleen een vaste set, waaronder Read, Grep, Glob, Bash, Edit, Write, WebFetch en WebSearch. Vraagt Claude onderweg om toestemming voor een tool, dan zie je die vraag in je hoofdgesprek, met de naam van de subagent erbij.

Drie voorbeelden

Drie Claude Code subagents om te kopiëren

Drie subagents die in de meeste projecten meteen nut hebben. Zet elk in een eigen bestand in .claude/agents/, met de naam die erboven staat. Wij hebben de drie bestanden op 29 oktober 2026 gecontroleerd met claude plugin validate .claude/agents; dat commando kun je zelf ook draaien na elke aanpassing, zie Werkt het?.

Voorbeeld 1: .claude/agents/reviewer.md

---
name: reviewer
description: Leest de laatste wijzigingen na op fouten, veiligheid en leesbaarheid. Gebruik na een afgeronde wijziging, voor een commit of pull request. Past zelf niets aan.
tools: Read, Grep, Glob, Bash
model: inherit
color: blue
---

Je bent een ervaren reviewer. Je past nooit zelf bestanden aan.

Werkwijze:
1. Draai git diff HEAD om te zien wat er veranderd is. Is dat leeg, draai dan git diff HEAD~1.
2. Lees alleen de gewijzigde bestanden en wat je nodig hebt om ze te begrijpen.
3. Controleer op: fouten in de logica, ontbrekende foutafhandeling, wachtwoorden of API-keys in de code, persoonsgegevens in logs, en namen die niet zeggen wat iets doet.

Rapporteer in het Nederlands, in drie groepen:
- Moet opgelost (met bestand en regelnummer)
- Zou beter zijn
- Ter overweging
Geef per punt in één zin waarom het ertoe doet. Maximaal 15 punten. Geen samenvatting van wat goed ging.

Waarom de reviewer zo is opgezet

Edit en Write staan niet in tools, dus kan hij geen bestanden bewerken of aanmaken; dat is een technische grens, geen verzoek. Bash staat er wel in, omdat hij git diff moet kunnen draaien. Daarmee kan hij in theorie nog steeds iets wijzigen via een shellcommando. Wil je dat ook uitsluiten, zet dan in je settings-bestand een deny-regel op de commando's die je niet wilt, of gebruik een PreToolUse-hook zoals in Claude Code hooks. model: inherit geeft hem hetzelfde model als je gesprek, omdat beoordelen meer vraagt dan zoeken. Het maximum van 15 punten houdt het rapport kort, zodat je hoofdgesprek niet alsnog volloopt.

Voorbeeld 2: .claude/agents/testrunner.md

---
name: testrunner
description: Draait de testsuite en meldt alleen de tests die falen, met de foutmelding. Gebruik na een wijziging als je wilt weten of de tests nog slagen.
tools: Read, Grep, Glob, Bash
model: haiku
maxTurns: 15
---

Je draait tests en rapporteert. Je past geen code aan.

1. Zoek uit hoe dit project tests draait: kijk in package.json, Makefile, pyproject.toml of de README.
2. Draai de volledige testsuite één keer.
3. Slagen alle tests, antwoord dan alleen: Alle tests geslaagd, met het aantal.
4. Falen er tests, geef dan per test: de naam, het bestand, de eerste vijf regels van de foutmelding en je vermoeden van de oorzaak in één zin.

Plak nooit de volledige testuitvoer in je antwoord.

Waarom de testrunner zo is opgezet

Testuitvoer is het schoolvoorbeeld van werk voor een subagent: honderden regels die jij nooit meer terugleest. Anthropic noemt het zelf als een van de nuttigste toepassingen. Hier blijft die uitvoer in het contextvenster van de subagent en krijg jij alleen de falende tests. model: haiku omdat tests draaien en een foutmelding samenvatten geen zwaar denkwerk is; dat spaart verbruik. maxTurns: 15 is een rem: blijft hij hangen in een kapotte testomgeving, dan stopt hij en hoor jij dat, in plaats van dat hij eindeloos doorzoekt. Voldoet Haiku niet, omdat de vermoedens over de oorzaak te vaak naast zitten, zet het model dan op sonnet.

Voorbeeld 3: .claude/agents/privacy-scan.md

---
name: privacy-scan
description: Zoekt in code, configuratie en testdata naar persoonsgegevens en geheimen, zoals BSN, IBAN, e-mailadressen, telefoonnummers en API-keys. Gebruik voor een release of als iemand vraagt of er gevoelige gegevens in de repository staan. Alleen lezen.
tools: Read, Grep, Glob
model: sonnet
---

Je controleert een repository op gegevens die er niet in horen. Je past niets aan en je herhaalt gevonden gegevens nooit volledig in je antwoord.

Zoek naar:
- Burgerservicenummers (negen cijfers) en IBAN-nummers (NL gevolgd door twee cijfers en vier letters)
- E-mailadressen en telefoonnummers van echte personen, buiten voorbeeld.nl of example.com
- API-keys, wachtwoorden en tokens in code, .env-bestanden die toch in de repository staan, en configuratie
- Exports of dumps met klantgegevens, zoals .csv-, .xlsx- of .sql-bestanden

Rapporteer per vondst: bestand, regelnummer, soort gegeven, en de eerste en laatste twee tekens met sterretjes ertussen. Sluit af met één zin: hoeveel vondsten, en welke het eerst weg moet.

Waarom de privacyscan zo is opgezet

Dit is de strengste van de drie: alleen Read, Grep en Glob, dus geen shell en geen schrijfrechten. Hij kan echt alleen kijken. Het maskeren van vondsten staat in de instructie, omdat zijn rapport in je hoofdgesprek belandt; zo staat een gevonden BSN niet nog een keer voluit in je gesprek. model: sonnet omdat het onderscheid tussen een testnummer en een echt nummer oordeel vraagt. Zie dit als een eerste zeef naast de controles die je al hebt, niet als vervanging van een echte privacycheck: een subagent vindt wat hij herkent, en een BSN zonder context is gewoon een getal van negen cijfers.

Fork of subagent

Fork of gewone subagent: wat is in Claude Code de standaard?

Een fork is een subagent die je hele gesprek tot nu toe meekrijgt, in plaats van leeg te beginnen. Hij heeft dezelfde instructie, dezelfde tools en hetzelfde model als je hoofdgesprek, dus je hoeft niets uit te leggen. Sinds versie 2.1.302 van 16 oktober 2026 staat de fork-modus standaard aan in de terminal (daar al sinds 2.1.232), in claude -p, de Agent SDK, de desktop-app en VS Code. Dat betekent dat Claude zelf een fork kan starten als hij werk uitbesteedt. Je eigen subagents blijven gewoon draaien zoals jij ze hebt ingesteld.

De vuistregel

Moet de taak alleen lezen of beoordelen, gebruik dan een eigen subagent met een beperkte tools-lijst, of de ingebouwde Explore. "Schrijf niets" in je opdracht aan een fork is een verzoek aan het model, geen grens: de fork heeft dezelfde schrijfrechten als jij. Wat daarbij in de praktijk misging, met twee echte meldingen op GitHub, lees je in Claude Code subagents en forks. Gebruik een fork als de taak je hele gesprek nodig heeft om zinnig te zijn, of als je twee aanpakken naast elkaar wilt laten uitwerken vanaf hetzelfde punt.

Zelf een fork starten met /subtask

Typ bijvoorbeeld /subtask schrijf unittests voor de wijzigingen hierboven en werk zelf door. De fork verschijnt in een paneel onder je invoervak. Met de pijltjestoetsen kies je een rij, Enter opent het verslag van die fork en laat je hem bijsturen, x stopt hem en Esc brengt je terug naar je invoervak. Als hij klaar is, komt zijn resultaat als bericht in je gesprek. Let op de naam: /fork doet iets anders. Dat kopieert je hele gesprek naar een losse achtergrondsessie, die niet terugrapporteert.

Forks uitzetten

Wil je niet dat Claude zelf forks start, zet dan in .claude/settings.json onder permissions een deny-regel: "deny": ["Agent(fork)"]. Wil je de hele fork-modus uit, zet dan in het env-blok van je settings-bestand "CLAUDE_CODE_FORK_SUBAGENT": "0" en start Claude Code opnieuw. Dat tweede heeft een bijeffect dat je misschien juist wilt: zolang de fork-modus aan staat, kan Claude in de terminal, VS Code en de desktop-app niet op een subagent wachten. Met de fork-modus uit kun je vragen draai de reviewer en wacht op zijn rapport. Wil je dan toch verder, druk dan op Ctrl+B om hem naar de achtergrond te sturen.

Werkt het?

Werkt het? Zo test je je Claude Code subagents

Je controleert drie dingen: worden de bestanden geladen, kiest Claude de goede subagent, en houdt de subagent zich aan zijn grenzen. Dat laatste test je bewust, op een manier waarbij er niets misgaat als het toch niet werkt.

De controle in drie stappen

1. Draai in je projectmap claude plugin validate .claude/agents. Je ziet Validation passed, of per bestand wat er mis is, zoals YAML die niet te lezen is. Waarom: Claude Code slaat een kapot bestand stil over; dit commando zegt het wel. Het controleert alleen de map die je noemt, en meldt niet een bestand zonder name.
2. Vraag in Claude Code: Welke subagents heb je in dit project beschikbaar, en wanneer zou je elk inzetten? Claude hoort reviewer, testrunner en privacy-scan te noemen, met ongeveer wat in hun description staat.
3. Test de grens: vraag Gebruik de privacy-scan-subagent om in README.md een regel toe te voegen met de datum van vandaag. Het goede resultaat is dat hij meldt dat hij niets kan aanpassen. Controleer daarna met git status dat README.md niet gewijzigd is. Omdat het om één onschuldige regel gaat, kan er niets kapot als het misgaat.

De eerste prompt om te plakken

Ik heb drie subagents in .claude/agents: reviewer, testrunner en privacy-scan.
1. Laat de testrunner de tests draaien.
2. Laat tegelijk de reviewer mijn laatste wijzigingen nalopen.
3. Wacht op beide rapporten en zet ze samen in één lijst, met bovenaan wat ik eerst moet oplossen.
4. Pas zelf nog niets aan. Stel alleen voor wat je zou wijzigen en waarom.

Waarom deze prompt werkt

Stap 1 en 2 staan los van elkaar, dus kunnen ze tegelijk draaien; Anthropic raadt parallel werk alleen aan als de taken niet van elkaar afhangen. Stap 3 laat Claude de twee samenvattingen combineren, niet de ruwe uitvoer: in je hoofdgesprek komen twee korte rapporten, niet honderden regels testuitvoer. Stap 4 houdt jou aan het stuur. Kijk na afloop met /usage hoeveel van je verbruik naar de subagents ging; op Pro, Max, Team en Enterprise splitst dat scherm het uit naar subagents, skills, plugins en MCP-servers.

Problemen

Claude Code subagents werken niet? Meldingen en oplossingen

Zoek je symptoom in de eerste kolom. Meldingen tussen aanhalingstekens komen letterlijk uit Claude Code. Kom je er niet uit, start dan claude --debug en zoek in het logbestand onder ~/.claude/debug naar de naam van je subagent: overgeslagen bestanden staan daar met de reden.

Ons oordeel

Ons oordeel: wanneer Claude subagents de moeite waard zijn

In onze trainingen zien we dat subagents het meeste opleveren bij werk met veel uitvoer en een kort antwoord: tests, logs, zoeken in een grote codebase, een vaste controle voor een release. Ze leveren het minste op bij werk waar je samen met Claude over moet nadenken.

Wanneer wel

Je merkt dat je gesprek vol raakt met testuitvoer, zoekresultaten of logs die je nooit meer terugleest. Je geeft Claude steeds dezelfde instructie voor hetzelfde soort klus. Of je wilt een harde grens: een reviewer die niets kan aanpassen, een scan die alleen mag lezen. Dan is een subagent een klein bestand dat zich snel terugverdient, omdat je hoofdgesprek langer bruikbaar blijft.

Wanneer niet

Bij een snelle, gerichte wijziging, of als je veel heen en weer wilt praten: een gewone subagent begint leeg en moet eerst context verzamelen, dus het duurt langer. Bij werk waar plannen, bouwen en testen dezelfde context delen. En bij een vraag over iets dat al in je gesprek staat: gebruik dan /btw, dat je hele context ziet zonder het gesprek te vullen. Wil je een vaste werkwijze die in je hoofdgesprek draait, maak dan een skill. Reken ook op verbruik: elke subagent stuurt eigen verzoeken, en vijf subagents die elk een lang rapport terugsturen vullen je gesprek alsnog.

De fout die we het vaakst zien: te veel agents tegelijk

Iemand vindt een verzameling met tientallen kant-en-klare subagents, zet ze allemaal in ~/.claude/agents en verwacht dat Claude er beter van wordt. Het omgekeerde gebeurt. Alle beschrijvingen staan in elk gesprek in je context, de beschrijvingen overlappen, en Claude kiest de verkeerde of geen. Begin met twee of drie subagents voor klussen die je deze week echt doet, met een description die zegt wanneer wel en wanneer niet. Voeg pas een vierde toe als je merkt dat je Claude steeds hetzelfde uitlegt. Hoe je een grote bundel selectief gebruikt, staat in Everything Claude Code.

Klantgegevens en de AVG

Een subagent stuurt wat hij leest naar Claude, net als je hoofdgesprek. Een privacyscan op een repository met klantgegevens verwerkt die gegevens dus ook; dat valt onder dezelfde afspraken met Anthropic als de rest van je Claude Code-gebruik. Twee dingen die mensen vergeten. Claude Code bewaart de verslagen van subagents lokaal in ~/.claude/projects/, standaard 30 dagen. En met memory: project schrijft een subagent zijn geheugen naar .claude/agent-memory/, dat mee gaat in git: zet in zijn instructie dat hij daar nooit klant- of persoonsgegevens in zet. Meer over de dataroutes lees je in Claude Code en privacy.

Een voorbeeld uit het MKB

Neem een installatiebedrijf met een eigen planningsapp, onderhouden door één ontwikkelaar in dienst en een freelancer die af en toe bijspringt. De app bevat klantadressen en telefoonnummers. Een werkbare start: de testrunner en de reviewer in .claude/agents van de repository, zodat de freelancer dezelfde krijgt zodra hij de code ophaalt, en de privacyscan als vaste stap voor elke release. De ontwikkelaar houdt zijn eigen hulpjes, zoals een subagent die release notes schrijft, in ~/.claude/agents. Zo staan de afspraken in de repository, en hoeft niemand ze uit zijn hoofd te kennen.

Wat nu?

Wat doe je na je eerste Claude Code subagents?

Werken de drie subagents, dan zijn dit de logische vervolgstappen. Kies er één, niet alles tegelijk.

Je subagents slimmer maken

Geef de reviewer een eigen geheugen met memory: project en zet in zijn instructie dat hij terugkerende fouten bijhoudt; dan hoef je jullie afspraken niet elke keer uit te leggen. Hoe dat werkt, met de worktree-optie en de achtergrond, staat bij de functies van Claude Code. Wil je een grens die fijner is dan de tools-lijst, zoals Bash wel maar git push niet, gebruik dan een hook: zie Claude Code hooks.

Subagents met een eigen koppeling

Met het veld mcpServers geef je één subagent een koppeling die je hoofdgesprek niet ziet, bijvoorbeeld een browser via Playwright. Dat scheelt context, omdat de toolbeschrijvingen dan alleen in die subagent staan. Hoe je zo'n koppeling eerst toevoegt, lees je in MCP-server toevoegen en Playwright MCP.

Naslag en verdieping

Alle velden, de ingebouwde agents en de limieten staan op een rij in Claude Code commands: subagents. Wat er precies verandert met forks, lees je in Claude Code subagents en forks, en wanneer een goedkoop model genoeg is in Claude Haiku 5.5 als subagent. Het begrip in één alinea staat in het woordenboek onder subagents; het verschil met meerdere sessies die met elkaar praten onder agent teams.

Met je team

Je instructies op orde brengen doe je met CLAUDE.md schrijven; daar zet je waarom de afspraken bestaan, de subagents voeren ze uit. Wil je reviews als vaste stap, lees dan Claude Code review. Wil je subagents, hooks en CLAUDE.md met je team als één werkwijze neerzetten, dan behandelen we dat in de Claude Code Masterclass.