# AI agent maken Claude Code: subagents, bestanden en 5 voorbeelden > Agentbestand, beschrijving, vijf complete sjablonen, parallelle uitvoering, Managed Agents, beperkingen en kosten, met voorbeelden intact. Source: https://ailoot.ai/blog/nl/claude-code-subagents/ Canonical: https://ailoot.ai/blog/nl/claude-code-subagents/ Language: nl Publisher: Ailoot (https://ailoot.ai/) Translation: guide-222 Revision: sha256-5210b7025c17b59f9016cc4bce0d5a1dfe2557a7106a2a2679d0b4e8d3be2b2d
Belangrijkste punten Een subagent in Claude Code is een gespecialiseerde AI-assistent met een eigen context, set tools en systeemprompt. De hoofdchat bepaalt zelf of een taak aan deze agent wordt gedelegeerd, of je kunt hem op naam aanroepen met `@agent-`. Een subagent voert een afgebakende taak uit zonder de hoofdconversatie te overladen en geeft alleen een eindsamenvatting terug. In deze gids leg ik uit hoe een subagent verschilt van een Skill, hoe je een beschrijving schrijft zodat Claude hem daadwerkelijk aanroept, en stel ik 5 werkende rollen samen in 30 minuten.
Praktische instructies voor het werken met Ailoot vind je in de [documentatie](https://ailoot.ai/docs/).
## Wat is een subagent in Claude Code, en waarom is het niet “zomaar een Skill”?
Belangrijkste punten Een subagent is een gespecialiseerde AI-assistent met een eigen context, systeemprompt en set tools. De officiële documentatie van Anthropic beschrijft het als een assistent die een neventaak in een afzonderlijke context uitvoert en alleen een samenvatting van het resultaat teruggeeft. In tegenstelling tot [Skills](https://ailoot.ai/blog/nl/claude-code-skills-library/), die in de hoofdchat worden geladen en met het geheugen daarvan werken, staat een subagent op zichzelf — en dat is zijn belangrijkste waarde.
De Claude Code-documentatie definieert het als volgt:

Subagents zijn gespecialiseerde AI-assistenten voor specifieke soorten taken. Gebruik een subagent wanneer een neventaak de hoofdconversatie zou vullen met zoekresultaten, logs of bestandsinhoud waar je later niets meer mee doet: de subagent voert dat werk uit in een eigen context en geeft alleen het resultaat terug.

— Claude Code-documentatie, https://code.claude.com/docs/en/sub-agents
In termen die een ondernemer begrijpt: stel je een makelaarskantoor voor. Er is een directeur, een marketeer, een jurist en er zijn verkoopmanagers. Eén medewerker die voortdurend tussen al die rollen wisselt, is geen team; het is een overbelast persoon. Een team ontstaat wanneer iedereen een eigen context en verantwoordelijkheidsgebied heeft, terwijl de directeur alleen taken toewijst en de resultaten samenbrengt. Subagents in Claude Code werken op dezelfde manier. De hoofdchat is de directeur. Een subagent is een specialist met een afgebakende taak, een eigen context en set tools. Wanneer een taak past bij de beschrijving van een specialist, delegeert de directeur die taak — zonder verstrikt te raken in de details. ### 5 doelen waarvoor Anthropic subagents heeft ontwikkeld De documentatie van Anthropic noemt precies vijf redenen om je eigen subagent te maken:

Subagents helpen je context te behouden door onderzoek en implementatie buiten de hoofdconversatie te houden; beperkingen af te dwingen door de tools die een subagent mag gebruiken te beperken; configuraties tussen projecten te hergebruiken met subagents op gebruikersniveau; gedrag voor specifieke domeinen te specialiseren met gerichte systeemprompts; en kosten te beheersen door taken door te sturen naar snellere, goedkopere modellen zoals Haiku.

— Claude Code-documentatie, https://code.claude.com/docs/en/sub-agents
Voor niet-programmeurs is **kostenbeheersing** het praktischste punt op deze lijst. Je kunt een omvangrijke onderzoekstaak naar het goedkope Haiku-model sturen en het hoofdgesprek voortzetten op Sonnet of Opus. De besparing op tokens is recht evenredig. ### Controleer nestingondersteuning voor je geïnstalleerde versie De sjablonen in deze gids gebruiken één hoofdsessie die rechtstreeks aan uitvoerders delegeert. Behandel oudere documentatie dat “subagents geen andere subagents kunnen starten” niet als tijdloze regel: nestinggedrag hangt af van de geïnstalleerde versie en toegestane tools. De [afzonderlijke gids voor geneste subagents](https://ailoot.ai/blog/nl/claude-code-nested-subagents/) bespreekt een versiegebonden recept. Controleer ondersteuning in je installatie voordat je diepere delegatie plant. ## Waarin verschilt een subagent van een Skill, Slash Command en Hook?
Belangrijkste punten Claude Code heeft vier uitbreidingsmechanismen en die zijn niet onderling uitwisselbaar. CLAUDE.md bevat permanente kennis die altijd wordt geladen. Skills zijn kant-en-klare methoden die bij activering in de hoofdchat worden geladen. Slash commands zijn expliciete `/command`-knoppen voor een eenmalige actie. Subagents zijn specialisten met een eigen context aan wie de hoofdchat werk delegeert. De meest voorkomende fout is een subagent maken terwijl je een Skill nodig hebt.
De vorige gids over [Skills](https://ailoot.ai/blog/nl/claude-code-skills-library/) legt uit dat Skills en slash commands in Claude Code in feite zijn samengevoegd tot één formaat. Maar een subagent is iets anders — niet simpelweg “een grotere Skill”. Een overzichtstabel van de vier mechanismen: | Kenmerk | CLAUDE.md | Skill | Slash command | Subagent | |----|----|----|----|----| | Wanneer wordt het geladen? | Altijd | Wanneer de beschrijving wordt geactiveerd | Bij een expliciet `/name`-commando | Bij delegatie of `@agent-name` | | Waar werkt het? | In de hoofdcontext | In de hoofdcontext | In de hoofdcontext | In de eigen geïsoleerde context | | Model | Hetzelfde als de hoofdchat | Hetzelfde | Hetzelfde | Elk model — Haiku, Sonnet, Opus, inherit | | Tools | Alle beschikbare | Erft over | Erft over | Kan worden beperkt met `tools:` | | Wat geeft het terug? | \- | Inline in de hoofdconversatie | Inline | Alleen de eindsamenvatting | | Parallelisme | \- | Nee | Nee | Ja — meerdere parallel | | Geheugen tussen sessies | Nabijgelegen bestanden | Nabijgelegen bestanden | Nabijgelegen bestanden | Het veld `memory: user/project/local` | Een goede formulering voor een Engelstalige gids: Skills zijn recepten; subagents zijn gespecialiseerde collega’s. Put simply: skills zijn recepten; subagents zijn gespecialiseerde collega’s. In de praktijk werkt het zo: Skills worden automatisch geactiveerd wanneer hun beschrijving bij de taak past, terwijl subagents expliciet worden aangeroepen — de hoofdchat besluit om te delegeren of je roept er een op naam aan. ### Beslisboom: “Welke moet ik kiezen?” Wanneer je denkt: “Ik wil Claude X laten doen”, loop dan deze vier vragen langs: 1. **Is dit kennis die altijd beschikbaar moet zijn?** Bijvoorbeeld: “we lokaliseren naar de voorkeurstaal van de gebruiker” of “we gebruiken geen em-dashes”. Zet het in `CLAUDE.md`. 2. **Is dit een methode die je nu handmatig uitvoert wanneer die wordt geactiveerd?** Bijvoorbeeld: “elke maandag schrijf ik een verkooprapport”. Maak een **Skill**. 3. **Is dit een taak die de context van de hoofdchat zal gebruiken, of kan die parallel worden uitgevoerd?** Bijvoorbeeld: “diepgaand onderzoek naar 30 bronnen” of “een beveiligingsaudit terwijl ik een nieuwe functie schrijf”. Maak een **subagent**. 4. **Heb je een automatische reactie nodig op een gebeurtenis in Claude Code?** Bijvoorbeeld: “voer de linter uit na elke Edit”. Schrijf een **Hook**. 90% van de taken van een ondernemer valt in de eerste twee categorieën. Subagents zijn een hulpmiddel voor gevorderden, voor wanneer je overstapt van “één taak tegelijk” naar orkestratie. ## Waar staan subagents, en welke heeft voorrang?
Belangrijkste punten Claude Code-subagents kunnen op vijf plaatsen staan, met verschillende prioriteiten — van beheerde instellingen van een organisatie tot plugins. Als twee bestanden dezelfde naam hebben, wint het bestand met de hogere prioriteit. De gebruikelijkste configuratie voor een zelfstandige ondernemer is `~/.claude/agents/` voor persoonlijke, algemene agents en `.claude/agents/` in een specifiek project voor projectspecifieke agents.
De hiërarchie van subagents heeft vijf niveaus, gerangschikt van hoogste naar laagste prioriteit: | Niveau | Pad | Geldt voor | Prioriteit | |----|----|----|----| | Enterprise | Beheerde instellingen van de organisatie | Alle medewerkers van het bedrijf | 1 (hoogste) | | Sessie | CLI-flag `--agents` met JSON | Alleen de huidige sessie | 2 | | Project | `.claude/agents/name.md` | Alleen dit project | 3 | | Persoonlijk | `~/.claude/agents/name.md` | Al je projecten | 4 | | Plugin | `/agents/name.md` | Overal waar de plugin is ingeschakeld | 5 (laagste) | De prioriteitslogica is hetzelfde als voor Skills en CLAUDE.md: organisatie gaat voor CLI, CLI voor project, project voor persoonlijk en persoonlijk voor plugin. ### Wat je moet weten over laden Subagents worden geladen wanneer een Claude Code-sessie start. Als je een agentbestand handmatig op schijf bewerkt, worden de wijzigingen pas opgepikt nadat je de sessie opnieuw start. Bewerkingen via de interactieve `/agents`-interface worden meteen toegepast. Eén subagent per bereik betekent één bestand. Als `.claude/agents/` `code-reviewer.md` bevat en er daarnaast nog een `code-reviewer.md` staat (bijvoorbeeld uit een oude back-up), zal Claude Code er stilzwijgend één negeren. Je krijgt geen melding. Subagents van plugins zijn een apart geval. Ze hebben beveiligingsbeperkingen: ze **ondersteunen de velden** `hooks`, `mcpServers` en `permissionMode` **niet**. Zo kan een plugin van derden na installatie geen toestemming krijgen om willekeurige code op je computer uit te voeren. ## De structuur van een subagentbestand: frontmatter en inhoud
Belangrijkste punten Een subagent is één Markdown-bestand met YAML-frontmatter bovenaan en daaronder een systeemprompt. Het minimum bestaat uit twee velden: `name` (kleine letters + koppeltekens) en `description` (wanneer Claude de taak moet delegeren). Het volledige schema bevat 16 velden: tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, color, initialPrompt. Anthropic raadt aan de beschrijving beknopt te houden — hoe duidelijker de trigger, hoe nauwkeuriger Claude de agent activeert.
Een minimaal voorbeeld uit de officiële documentatie — slechts 9 regels: ```markdown --- name: code-reviewer description: Reviews code for quality and best practices tools: Read, Glob, Grep model: sonnet --- You are a code reviewer. When invoked, analyze the code and provide specific, actionable feedback on quality, security, and best practices. ``` Dat is voldoende. Als een gebruiker in de hoofdchat zegt “review my PR”, koppelt Claude “reviewer / code / quality” aan de beschrijving en delegeert het werk aan de subagent. De subagent leest de diff, geeft commentaar en stuurt een samenvatting terug naar de hoofdchat. Die wordt niet volgestopt met logs en tussentijdse analyses. ### Het volledige frontmatter-schema | Veld | Verplicht | Functie | |----|----|----| | `name` | Ja | Unieke identificatie, kleine letters + koppeltekens. De bestandsnaam hoeft NIET overeen te komen | | `description` | Ja | Wanneer Claude delegeert. Dit is de automatiseringstrigger | | `tools` | Nee | Lijst met toegestane tools. Als dit ontbreekt, erft de agent alle tools van de bovenliggende agent | | `disallowedTools` | Nee | Blokkeerlijst. Wordt EERST toegepast, daarna `tools` | | `model` | Nee | `haiku` / `sonnet` / `opus` / volledige ID / `inherit` (standaard) | | `permissionMode` | Nee | `default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan` | | `maxTurns` | Nee | Limiet voor het aantal stappen voordat de agent stopt | | `skills` | Nee | Skills die bij het opstarten in de context van de subagent worden geladen | | `mcpServers` | Nee | MCP-servers die alleen voor deze subagent beschikbaar zijn | | `hooks` | Nee | PreToolUse / PostToolUse / Stop, beperkt tot deze subagent | | `memory` | Nee | `user` / `project` / `local` — map voor geheugen tussen sessies | | `background` | Nee | `true` — altijd op de achtergrond uitvoeren. Standaard `false` | | `effort` | Nee | `low` / `medium` / `high` / `xhigh` / `max` — redeneerniveau | | `isolation` | Nee | `worktree` — uitvoeren in een afzonderlijke git-worktree | | `color` | Nee | UI-kleur: red / blue / green / yellow / purple / orange / pink / cyan | | `initialPrompt` | Nee | Eerste zin die de subagent ziet wanneer die via `--agent` wordt gestart | Het veld `model: haiku` is precies die “kostenbeheersing” uit de lijst met vijf doelen. Als je een onderzoeksagent hebt die 50 pagina’s documentatie leest, gebruik dan Haiku om 5–7 keer goedkoper uit te zijn dan met Opus. Het veld `isolation: worktree` lost een belangrijk probleem op: een subagent voert mogelijk riskante wijzigingen uit (refactoring, migratie), maar je wilt niet dat die je werkmap aanraakt. Stel `isolation: worktree` in en Claude Code maakt een tijdelijke git-kopie van het project; de subagent werkt daarin en geeft een diff terug ter beoordeling. ### De inhoud van het bestand is de systeemprompt Na de frontmatter volgt gewone Markdown — de systeemprompt van de subagent. Een speciale structuur is niet nodig, maar dit is een beproefd patroon: 1. **Wie je bent** — één zin: “je bent een code-reviewer”, “je bent een beveiligingsauditor”, “je onderhoudt documentatie”. 2. **Wanneer je wordt aangeroepen en wat je eerst doet** — de eerste 2–3 acties na ontvangst van de taak. 3. **Een checklist met controles of stappen** — 5–10 punten die de subagent volgt. 4. **Wat je teruggeeft** — het formaat van het eindrapport. Dit is cruciaal: als je geen formaat opgeeft, produceert de subagent een “essay” in plaats van een gestructureerde samenvatting. 5. **Wat je NIET doet** — expliciete beperkingen. Zonder dit onderdeel gaat de subagent improviseren. Houd de inhoud van het bestand tussen 200 en 500 regels. Als het langer wordt, verplaats uitgebreide referenties naar afzonderlijke bestanden in de buurt en verwijs ernaar in de prompt. ## Zo schrijf je een beschrijving waardoor Claude je subagent zeker aanroept
Belangrijkste punten Description is het enige veld dat Claude aan het begin van een sessie ziet en gebruikt om te beslissen of het werk delegeert. De meest gehoorde klacht op forums is: “Ik heb een subagent geschreven, maar Claude roept hem niet aan.” De oplossing is een formule in drie delen: wat de agent doet + triggerzinnen tussen aanhalingstekens + wanneer je hem NIET moet gebruiken. Anthropic raadt expliciet aan om zinnen als “use proactively” of “use immediately after” in de beschrijving op te nemen om Claude aan te moedigen de agent aan te roepen.
Een veelvoorkomend probleem is dat Claude bij een ingestelde subagent voor code-review alles zelf doet zonder de agent te gebruiken. Meestal is daar één reden voor: de beschrijving luidt “Helper for code review”. Claude begrijpt niet wanneer die moet worden geactiveerd. ### Formule voor een effectieve beschrijving (3 delen) **Deel 1 — wat de agent doet.** Eén zin over het resultaat, niet het proces. Niet “analyseert code”, maar “vindt kwetsbaarheden in code en geeft een lijst met ernst en een oplossing”. **Deel 2 — wanneer de agent moet worden geactiveerd.** 3–5 zinnen tussen aanhalingstekens die gebruikers echt als verzoek formuleren. Raad niet — kijk in je chatgeschiedenis en naar de formuleringen die mensen daadwerkelijk gebruiken. **Deel 3 — wanneer de agent NIET moet worden geactiveerd.** 1–2 zinnen over vergelijkbare taken waarop deze subagent niet moet reageren. Zonder dit onderdeel komen twee vergelijkbare agents voortdurend met elkaar in conflict. ### De magische zin “Use Proactively” De officiële documentatie van Anthropic doet een directe aanbeveling:

Claude delegeert taken automatisch op basis van de taakbeschrijving in je verzoek, het description-veld in de configuratie van de subagent en de huidige context. Voeg zinnen als 'use proactively' toe aan de beschrijving van de subagent om proactieve delegatie aan te moedigen.

— Claude Code-documentatie, https://code.claude.com/docs/en/sub-agents
Met andere woorden: Claude zal standaard niet snel een subagent aanroepen als de beschrijving geen duidelijke signalen bevat. Voeg “use proactively” of “use immediately after writing code” toe en de kans op activering stijgt sterk. ### Een sterke beschrijving ziet er zo uit ```yaml description: | Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. Returns prioritized list of issues with severity and fix recommendations. Do not invoke for documentation changes, README edits, or commit message rewrites - these are handled by doc-maintainer. ``` Waarom dit werkt: - De werkwoorden “reviews” + “returns” geven een concreet resultaat aan, geen proces. - “Proactively” en “immediately after” zijn expliciete triggers. - “Do not invoke for...” voorkomt conflicten met een vergelijkbare subagent. - Een Engelstalige beschrijving is gebruikelijk. Claude herkent overeenkomsten beter in het Engels. ## 5 kant-en-klare subagentrollen die in 10 minuten werken
Belangrijkste punten Om je eerste subagent niet helemaal vanaf nul te hoeven schrijven, kun je beproefde patronen gebruiken en aanpassen. Ik heb 5 rollen beschreven voor veelvoorkomende taken: code-reviewer (code beoordelen na wijzigingen), security-auditor (kwetsbaarheden en datalekken vinden), research-agent (diepgaand onderzoek naar 8+ bronnen), doc-maintainer (documentatie met de code synchroniseren) en refactor-agent (veilig refactoren via een git-worktree). Bij elke rol hoort een kant-en-klaar sjabloon dat je kunt kopiëren en aanpassen.
Elke rol hieronder is één bestand: `.claude/agents/.md`. Start Claude Code opnieuw nadat je het bestand hebt gemaakt, open `/agents` en controleer of de nieuwe agent in de lijst staat. Daarna kun je hem aanroepen met `@agent-name`. ### 1. code-reviewer — code beoordelen na elke wijziging Dit is het officiële voorbeeld uit de documentatie van Anthropic, aangepast voor een werkproces: ```markdown --- name: code-reviewer description: | Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. tools: Read, Grep, Glob model: inherit color: blue --- You are a senior code reviewer ensuring high standards of code quality. When invoked: 1. Read the diff and changed-file list supplied by the main session. If missing, ask the main session to provide them. 2. Use Read, Grep, and Glob to inspect the relevant files. 3. Return findings without changing files or running shell commands. Review checklist: - Code is clear and readable - Functions and variables are well-named - No duplicated code - Proper error handling - No exposed secrets or API keys - Input validation implemented - Test coverage adequate - Performance considerations addressed Provide feedback organized by priority: - Critical issues (must fix before merge) - Warnings (should fix) - Suggestions (consider improving) Format: for each issue - file:line + 1 sentence why it's a problem + concrete fix. ``` De kern is `tools: Read, Grep, Glob`: de reviewer heeft lees- en zoektools, zonder Bash, Write of Edit. De hoofdsessie maakt de diff en geeft die door. Alleen de instructie geven om `git diff` uit te voeren zou een volledig toegekende Bash-tool niet beperken. ### 2. security-auditor — kwetsbaarheden en datalekken vinden Deze rol gebruikt `opus` voor diepere redenering en dezelfde beperking tot Read, Grep en Glob. Blijvend geheugen is weggelaten uit dit alleen-lezen-sjabloon omdat agentgeheugen inschakelen ook de mogelijkheid geeft om geheugen te schrijven: ```markdown --- name: security-auditor description: | Security audit specialist. Use proactively to find OWASP Top 10 vulnerabilities, exposed secrets, injection risks, broken auth. Run before any deploy or merge to main. tools: Read, Grep, Glob model: opus color: red --- You are a security auditor. Find exploitable vulnerabilities, not style issues. Audit checklist: - SQL / NoSQL injection - XSS (stored, reflected, DOM-based) - CSRF / SSRF risks - Hardcoded secrets (API keys, tokens, passwords) - Broken auth / session management - Insecure deserialization - Missing input validation - Path traversal - Open redirects - Insecure direct object references (IDOR) For each finding: - Severity: Critical / High / Medium / Low - File:line - Attack scenario in 1–2 sentences - Fix recommendation with code example Skip linter or style noise. Report only exploitable issues. ``` Wat tools betreft is dit alleen-lezen; voor complexe controles, zoals reeksen kwetsbaarheden, gebruik je `model: opus`. ### 3. research-agent — diepgaand onderzoek naar 8+ bronnen Dit patroon wordt beschreven in het artikel van Anthropic over hun multi-agent-onderzoekssysteem. Belangrijk zijn een expliciet uitvoerformaat en het verbod om ruwe resultaten te dumpen: ```markdown --- name: research-agent description: | Deep web research specialist. Use proactively for fact-finding, competitive analysis, gathering external documentation, comparing approaches across multiple sources. tools: WebFetch, WebSearch, Read, Write model: sonnet maxTurns: 30 color: purple --- You are a research analyst. Goal: synthesized brief, not raw search dumps. Process: 1. Decompose the question into 3–5 sub-queries 2. WebSearch each sub-query, fetch top 3–5 sources per query 3. Cross-verify claims across at least 2 independent sources 4. Reject SEO-farm and aggregator content; prefer primary sources 5. Quote verbatim with URL attribution for any specific claim 6. Return: TL;DR (3 bullets) + Findings + Sources (8+ domains minimum) Anti-patterns to avoid: - Don't cite a fact from a single source - Don't paraphrase quotes as if they were verbatim - Don't return raw search result dumps to the parent - Don't include filler intro / outro ("Hope this helps") ``` `maxTurns: 30` is een beveiliging tegen onderzoek dat eindeloos doorgaat. Anthropic noemt dit aantal in hun multi-agent-systeem:

Een multi-agentsysteem met Claude Opus 4 als hoofdagent en Claude Sonnet 4 als subagents presteerde 90.2% beter dan één Claude Opus 4 op onderzoekstaken uit de benchmark.

— Anthropic Engineering, https://www.anthropic.com/engineering/multi-agent-research-system
De negentig procent heeft betrekking op onderzoekstaken uit de benchmark. In de praktijk is de winst kleiner voor zakelijke taken, maar de algemene orde van grootte is vergelijkbaar. ### 4. doc-maintainer — documentatie synchroon houden met de code Deze rol gebruikt `model: haiku` — een typisch voorbeeld van “kostenbeheersing”. Voor documentatie is Opus niet nodig; Haiku klaart de klus voor een derde van de prijs: ```markdown --- name: doc-maintainer description: | Documentation sync specialist. Use after merging features to update README, API docs, CHANGELOG. Reads recent commits, identifies undocumented changes, updates docs proactively. tools: Read, Write, Edit, Glob, Grep, Bash model: haiku memory: project color: green --- You maintain documentation in sync with code. When invoked: 1. Run `git log --since="last release"` to see recent changes 2. Read README.md, docs/, CHANGELOG.md 3. Identify gaps: new features without docs, removed APIs still documented, version mismatches Output: - Updated files (use Edit, not Write - preserve existing structure) - CHANGELOG.md entry in Keep-A-Changelog format - List of changes you made (actual diff summary, not paraphrase) Style rules: - Active voice, present tense - Code examples must be copy-pasteable - No marketing language ("powerful", "robust", "seamless") - No filler ("This guide will help you...") ``` ### 5. refactor-agent — veilig refactoren via een worktree Deze rol gebruikt `isolation: worktree` — de subagent werkt in een afzonderlijke kopie van de repository, en je voegt de wijzigingen alleen samen als ze in orde zijn: ```markdown --- name: refactor-agent description: | Safe refactor specialist. Use for renames, extracts, inlines that shouldn't touch your working copy until reviewed. Runs in a temporary git worktree. tools: Read, Edit, Write, Bash, Grep, Glob model: sonnet isolation: worktree permissionMode: acceptEdits color: yellow --- You refactor code without changing behavior. Strict rules: 1. Tests must pass BEFORE and AFTER the refactor. If pre-refactor tests fail, STOP and report. 2. One atomic refactor per commit (extract, rename, inline). 3. Never change public APIs without explicit instruction. 4. Never modify tests unless they test the refactored implementation directly. Process: - Run test suite -> baseline - Make atomic refactor - Run test suite -> verify - Commit with conventional message: refactor(scope): what Return: summary of changes + worktree path so user can diff and merge. ``` Met deze rol verdwijnt het pijnlijkste refactoringprobleem — “ik heb iets stukgemaakt en weet niet hoe ik het terugdraai” — want de oorspronkelijke kopie blijft intact terwijl de subagent in een geïsoleerde worktree werkt. Wil je niet alleen kant-en-klare subagents kopiëren, maar **een combinatie samenstellen die Claude tot een stabiel hulpmiddel maakt**? Subagents zijn onderdeel van je **AI-kloon**: een manier om Claude een gespecialiseerd team te geven dat volgens jouw logica werkt. De drie pijlers van de methode zijn: **AI-kloon** (Skills + Subagents) + **[Tweede Brein](https://ailoot.ai/blog/nl/tweede-brein-claude-code/)** + **Context Engineering**. Deze combinatie verandert Claude van een assistent die gokt in een hulpmiddel dat volgens jouw logica denkt. ## 5 subagents parallel starten: orkestrator + uitvoerders
Belangrijkste punten De grootste kracht van subagents is parallelle uitvoering. Eén hoofdchat houdt het plan vast, terwijl vijf (of tien) gespecialiseerde subagents tegelijk aan verschillende fasen werken, elk in hun eigen context. De hoofdchat verzamelt en controleert de resultaten. Dat versnelt het werk 3–5 keer ten opzichte van opeenvolgend werken en voorkomt ook “contextvervuiling”, waarbij de hoofdconversatie bedolven raakt onder logs en tussentijdse analyses.
Parallelle orkestratie is een opzet van “dirigent + orkest”. De dirigent houdt het plan vast, schrijft de noten niet en controleert wat de muzikanten spelen. Als iemand een verkeerde noot speelt, vraagt de dirigent diegene opnieuw te spelen in plaats van het werk zelf af te maken. Voor een ondernemer is een marketingbureau dat een strategie voor een nieuwe klant voorbereidt een betere vergelijking. Eén analist maakt een SWOT-analyse, een ander analyseert concurrenten, een derde maakt een publieksprofiel, een senioranalist schrapt hypotheses die niet binnen het budget passen en de projectmanager stelt de eindpresentatie samen. In Claude Code begint deze workflow met één zin, en de criticus maakt al deel uit van het proces in plaats van pas achteraf te verschijnen. ### Minimale orkestratieprompt Eén zin in de hoofdchat is genoeg: ``` Start vijf subagents parallel: drie research-agents voor verschillende bronnen (Anthropic-documentatie, GitHub-repositories, AI-bloggers), één critic-agent om zwakke conclusies te filteren en één summary-agent voor het einddocument. Context: ik schrijf een gids over X. Gewenste lengte: 2,000 woorden met bronnen. Laat ieder van hen vóór de start CLAUDE.md lezen. ``` Claude delegeert vervolgens aan de vijf agents. Elk werkt in een eigen context: de research-agents gebruiken hun respectieve bronnen, de critic filtert en de summary-agent stelt alles samen. Alleen eindsamenvattingen gaan terug naar de hoofdchat. ### Wanneer parallel werken loont Niet overal. Parallelle uitvoering is alleen zinvol wanneer: 1. Taken **onafhankelijk** zijn. Als research-agent #2 wacht op het resultaat van research-agent #1, is er geen parallelisme — ze werken dan feitelijk na elkaar. 2. Taken **veel tijd kosten**. “Witruimte aan het einde verwijderen” parallel uitvoeren heeft geen zin; de overhead van het starten van subagents maakt de winst ongedaan. 3. Je **voldoende limieten** hebt. Daarover lees je hieronder meer — parallelle subagents verbruiken snel veel tokens. ### Anthropic’s Multi-Agent v2: een volgende stap In mei 2026 bracht Anthropic Multi-Agent Orchestration v2 uit, met drie belangrijke verschillen ten opzichte van de klassieke aanpak waarbij je parallelle subagents start. Daarover meer in de volgende sectie. ## Wat is nieuw in Multi-Agent v2: Orchestration, Outcomes, Dreaming
Belangrijkste punten Op 6 mei 2026 kondigde Anthropic tijdens de Code with Claude-conferentie in San Francisco drie functies van Managed Agents v2 aan — alle in publieke bèta. Met Multi-Agent Orchestration kan een hoofdagent werk opsplitsen en parallel delegeren aan specialisten met een gedeeld bestandssysteem. Met Outcomes kun je een succesrubric opstellen, waarna een afzonderlijke beoordelaar het resultaat controleert. Dreaming is als REM-slaap: een gepland proces leest eerdere sessies, vindt patronen en werkt het agentgeheugen bij.
### Multi-Agent Orchestration: gedeeld bestandssysteem + tussentijdse controles Anthropic beschrijft de functie als volgt:

Wanneer het werk te omvangrijk is voor één agent, kan een hoofdagent met multi-agent-orkestratie de taak in stukken verdelen en elk stuk delegeren aan een specialist met een eigen model, prompt en tools. Deze specialisten werken parallel op een gedeeld bestandssysteem en voeren hun resultaten aan de gedeelde context van de hoofdagent toe.

— Anthropic - Nieuw in Claude Managed Agents, https://claude.com/blog/new-in-claude-managed-agents
Het belangrijkste verschil met klassieke subagents is een **gedeeld bestandssysteem**. Voorheen werkte elke subagent volledig geïsoleerd en werden resultaten alleen uitgewisseld via de samenvatting die werd teruggestuurd. Nu kunnen specialisten naar een gedeelde map schrijven en kan de hoofdagent resultaten tijdens het werk lezen, niet pas aan het einde. Zo wordt het probleem opgelost dat “iedereen de hele dag heeft gewerkt, maar aan het einde bleek dat twee mensen onverenigbare aanpakken hadden”. Ten tweede zijn er **tussentijdse controles**. De hoofdagent kan pauzeren en een specialist vragen “hoe gaat het?”, en vervolgens het algemene plan aanpassen. Dat lijkt op hoe een echte teammanager werkt. ### Outcomes: een rubric in plaats van stapsgewijze instructies Met Outcomes schrijf je succescriteria op en vindt de agent een manier om eraan te voldoen. Een afzonderlijke beoordelaar controleert het resultaat in zijn eigen context, zodat het niet wordt “besmet” door de redenering van de hoofdagent.

Dit verbeterde het succespercentage bij het oplossen van taken met maximaal 10 punten ten opzichte van de standaard promptcyclus, met de grootste winst bij de lastigste taken.

— Anthropic - Nieuw in Claude Managed Agents, https://claude.com/blog/new-in-claude-managed-agents
Tien procent winst bij uitdagende taken is een aanzienlijk verschil. Vooral wanneer een taak is geformuleerd als “stel een lang artikel samen dat aan deze kwaliteitscriteria voldoet”, en niet als “volg stap 1–7”. ### Dreaming: agents doen ervaring op tussen sessies Dit is de conceptueel nieuwste functie. Een agent doorloopt eerdere sessies, vindt patronen in successen en fouten en werkt het geheugenarchief bij. Je kunt handmatige controle instellen voordat wijzigingen worden toegepast, of de agent zelf het geheugen laten aanpassen. Anthropic meldt dat Harvey (een juridisch-technologiebedrijf) na de invoering van Dreaming ongeveer een zesvoudige stijging zag in het succes van taken voor het opstellen van juridische documenten. Dit werkt al in productie en is niet alleen een demo. ### Wat betekent dit voor ondernemers die niet programmeren? Multi-Agent Orchestration is momenteel beschikbaar via de Claude Agent SDK, niet rechtstreeks in de Claude Code CLI. De richting is echter duidelijk: orkestratie verschuift van “je start handmatig N subagents” naar “je beschrijft de taak en de hoofdagent bepaalt aan wie die wat delegeert”. Als je net met subagents begint, hoef je je nog geen zorgen te maken over v2. Leer eerst het klassieke patroon van “1 hoofdchat + 3–5 subagents met verschillende rollen”; over 3–6 maanden kun je vanzelf overstappen naar Managed Agents. ## 7 fouten die subagents meteen laten vastlopen
Belangrijkste punten De meest voorkomende problemen met subagents zijn geen bugs in Claude, maar fouten in de subagents zelf. Beschrijvingen zonder triggerzinnen, een subagent inzetten voor een taak die bij een Skill past, “omdat het cool is” 60 agents parallel laten draaien, elke agent alle tools geven, geen expliciet uitvoerformaat opgeven, vage opdrachten en een architectuur op basis van rollen in plaats van taken. Elk van deze fouten ondermijnt de activering of de resultaten van de subagent.
### Fout 1. Beschrijvingen als “Helper for X” activeren de agent niet Symptoom: je hebt een subagent geschreven, de structuur gecontroleerd en alles is geldig, maar Claude roept hem niet aan voor verzoeken van gebruikers. De reden is bijna altijd dezelfde: de beschrijving is abstract, zoals “Helper for code review”. De oplossing: zet 3–5 echte gebruikerszinnen tussen aanhalingstekens rechtstreeks in de beschrijving, plus “use proactively” / “use immediately after”. ### Fout 2. Een subagent maken terwijl je een Skill nodig hebt Een subagent kost meer dan een Skill: hij maakt een eigen context aan, laadt een eigen systeemprompt en verbruikt meer tokens. Als een taak kort is, de hoofdcontext niet gebruikt en in één keer kan worden uitgevoerd, moet je er een Skill voor maken, geen subagent. Een voorbeeld van een antipatroon: een `format-validator`-subagent die een JSON-schema aan 20 regels toetst. Dat hoort een Skill te zijn: één model, geen isolatie nodig en geen extra context geladen. ### Fout 3. Meteen “60 parallelle agents” starten Dit is de meest wijdverbreide illusie. Je ziet een tweet met “Ik heb 1,500 agents aan het werk” en denkt: “Dat moet ik ook doen.” In de praktijk verbruiken 60 agents binnen een uur de limieten van een Pro-abonnement, produceren ze een stapel tegenstrijdige resultaten en heb je aan het einde van de dag niets afgerond. Een gebruiker op Medium formuleert het zo: De oplossing: begin met één subagent voor één taak. Heb je dat onder de knie, voeg dan een tweede toe met een andere rol. Zodra je twee agents kunt orkestreren, ga je over op een team van 3–5. Van “gisteren Claude Code geïnstalleerd” naar “vandaag 20 parallel” springen, zal zeker code stukmaken en limieten verbruiken. ### Fout 4. Elke agent alle tools geven Als je code-reviewer toegang heeft tot Bash, Write en WebFetch, is dat een groot beveiligings- en kostengat. Een reviewer hoeft geen bestanden te kunnen schrijven, laat staan het internet op. De oplossing: beperk `tools` strikt. Geef een code-reviewer alleen `Read, Grep, Glob`. Een beveiligingsauditor krijgt dezelfde lees- en zoektools en een diff van de hoofdsessie. Bash toevoegen geeft shellmogelijkheden; dat beperkt de agent niet automatisch tot `git diff`. Een research-agent krijgt `WebFetch, WebSearch, Read, Write`. Geef een subagent niet meer bevoegdheden dan nodig zijn voor één specifieke taak. ### Fout 5. Een subagent dumpt ruwe resultaten in de hoofdcontext Als een research-agent de hoofdchat “hier zijn alle 30 pagina’s die ik heb gevonden; zoek het zelf maar uit” terugstuurt, ben je het grootste voordeel van subagents kwijt: ruisisolatie. De oplossing: eis expliciet een uitvoerformaat in de systeemprompt van de subagent. “Geef ALLEEN terug: TL;DR in 3 bullets + lijst met 5 bronnen. GEEN codedumps, GEEN ruwe zoekresultaten.” Dit formaat moet **strikt** zijn — de subagent mag niet zelf besluiten er “een essay van te maken”. ### Fout 6. Vage aanroepen: onduidelijke delegatieverzoeken Een subagent **kan** de geschiedenis van de hoofdconversatie **niet zien**. Hij begint met een schone context + CLAUDE.md + alles wat je expliciet hebt geschreven. Als je “fix authentication” schrijft, zal de subagent dingen verzinnen. Schrijf in plaats daarvan: “Los de OAuth-redirectlus op waarbij de gebruiker na een geslaagde aanmelding naar /login wordt gestuurd in plaats van naar /dashboard. Bestand: src/lib/auth.ts.” Een duidelijke regel: geef bij delegatie evenveel context als aan een nieuwe opdrachtnemer die net bij het project is gekomen. ### Fout 7. Agents op basis van rollen in plaats van taken Een verleidelijk patroon is: “laten we een frontend-developer, backend-developer en qa-engineer maken en ze als team laten werken.” Dat werkt niet. Elke “rol” verliest de context van het hele project en de agents kunnen het niet eens worden over details, omdat ze elkaar niet kunnen zien. De oplossing: een subagent moet een terugkerende **taak** met een duidelijke uitvoer hebben, geen **rol**. Niet “frontend-developer”, maar “explore-ui-tree”, “refactor-component”, “audit-accessibility”. Elke taakgerichte subagent doet één specifieke klus en geeft één specifiek resultaat terug. ## Hoeveel kosten parallelle subagents, en wanneer zijn ze de moeite waard?
Belangrijkste punten Parallelle subagents verbruiken tokens 3–5 keer sneller dan opeenvolgend werk. Met een Pro-abonnement (\$20/month) verbruik je de tegoeden in een uur als je 5 parallelle subagents start. Max 5x (\$100/month) is een realistisch minimum voor regelmatig parallel werk. Een subagent loont bij taken die minstens 10 minuten geconcentreerd werk vragen — er een starten voor een typefout in een README kost meer tokens dan de tijd die je ermee bespaart.
| Configuratie | Dagelijks gebruik bij actief werk | |----|----| | 1 Claude Code-sessie | ~\$13 | | 3 parallelle subagents | ~\$30-40 | | 5–10 parallel | \$50-130 | | 30 agents (10 developers × 3 subagents) | \$300-400 | Bij complexe taken is een Pro-abonnement binnen een uur op als je 5 parallelle subagents start. Max 5x ($100) is een realistisch minimum voor regelmatig parallel werk. Voor teams en Enterprise is het geldvraagstuk al geregeld op het niveau van het toolingbudget. Lees de [aparte gids over limieten](https://ailoot.ai/blog/nl/claude-code-token-limits-saving/) voor meer informatie over tokens besparen in Claude Code. Voor subagents geldt als hoofdregel dat ze de moeite waard zijn bij een taak die **minstens 10 minuten** geconcentreerd werk vraagt. Is de taak korter, maak dan geen subagent; voer hem uit in de hoofdchat of met een Skill. ## Hoe integreer je subagents in je AI-kloon en Tweede Brein?
Belangrijkste punten Subagents zijn de vierde stap in de Claude Code-methodologie. De logische volgorde is: eerst [CLAUDE.md](https://ailoot.ai/blog/nl/claude-md-template/) (permanente context), daarna [Skills](https://ailoot.ai/blog/nl/claude-code-skills-library/) (kant-en-klare methoden), vervolgens [Tweede Brein](https://ailoot.ai/blog/nl/tweede-brein-claude-code/) (kennisstructuur voor het project) en pas daarna subagents (gespecialiseerde uitvoerders). Draai je deze volgorde om, dan krijg je hype zonder resultaat. Zonder CLAUDE.md verzint een subagent dingen; zonder Skills herhaalt hij telkens hetzelfde werk vanaf nul; zonder kennisstructuur geeft hij een gemiddeld antwoord.
Een subagent steunt op drie dingen die in je project aanwezig moeten zijn voordat je je eerste specialist maakt: 1. **De juiste [CLAUDE.md](https://ailoot.ai/blog/nl/claude-md-template/).** Een subagent leest CLAUDE.md voordat hij begint — het is zijn “arbeidscontract”. Zonder dat bestand kent een subagent de projectcontext, beperkingen of toon niet. Hij gaat dingen verzinnen. 2. **Basis-[Skills](https://ailoot.ai/blog/nl/claude-code-skills-library/).** Een Skill is een verpakte methode. Een subagent laadt alleen de Skills die hij nodig heeft, niet alles tegelijk. Zonder Skills herhaalt een subagent telkens hetzelfde werk vanaf nul. 3. **[Tweede Brein](https://ailoot.ai/blog/nl/tweede-brein-claude-code/): een kennisstructuur.** De map `business/` (of het equivalent daarvan in jouw vakgebied) is een bibliotheek die alle subagents raadplegen. Zonder deze structuur geeft een subagent een gemiddeld ChatGPT-antwoord dat niet te onderscheiden is van dat van anderen. Als je deze volgorde omdraait, krijg je hype zonder resultaat. “Ik heb 60 parallelle subagents” zeggen terwijl de map `business/` leeg is, betekent dat je 60 gemiddelde ChatGPT-sessies dezelfde aanpak laat volgen. De volledige combinatie — **AI-kloon + Tweede Brein + Context Engineering** — bestaat uit de **drie pijlers** die Claude consistent maken. Subagents zijn onderdeel van de AI-kloon: een manier om Claude een gespecialiseerd team te geven dat volgens jouw logica werkt.
### Bronnen - [Aangepaste subagents maken - Claude Code-documentatie](https://code.claude.com/docs/en/sub-agents) - [Claude Code autonomer laten werken - Anthropic News](https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously) - [Hoe we ons multi-agent-onderzoekssysteem hebben gebouwd - Anthropic Engineering](https://www.anthropic.com/engineering/multi-agent-research-system) - [Agents toerusten voor de echte wereld met Agent Skills - Anthropic Engineering](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) - [Nieuw in Claude Managed Agents (Multi-Agent v2, Outcomes, Dreaming) - Anthropic-blog](https://claude.com/blog/new-in-claude-managed-agents)
De snelste manier om te beginnen is `code-reviewer` uit het eerste voorbeeld hierboven te kopiëren naar `.claude/agents/code-reviewer.md`, Claude Code opnieuw te starten en `@agent-code-reviewer` aan te roepen bij je volgende commit. In 5 minuten weet je of je subagents nodig hebt of dat de hoofdchat volstaat.
Je kunt Ailoot verder ontdekken op [ailoot.ai](https://ailoot.ai/).
## Vragen en antwoorden ### Kan een reviewer alleen git diff uitvoeren omdat de prompt dat zegt? Nee. Bash toekennen geeft shellmogelijkheden; de prompt is geen toelatingslijst voor opdrachten. Het alleen-lezen-sjabloon laat Bash, Write en Edit weg en ontvangt de diff van de hoofdsessie. ### Hoe bekijkt een reviewer recente wijzigingen zonder Bash? De hoofdsessie geeft bij de delegatie de diff en lijst met gewijzigde bestanden mee. De reviewer leest en doorzoekt die bestanden daarna met Read, Grep en Glob en geeft bevindingen terug zonder bestanden te bewerken. ## Ailoot · Het bedrijf en zijn projectenportefeuille Ailoot bouwt op opgebouwde operationele ervaring, een groot klantenbestand, een stabiele dienst en doorlopende KPI-controle. Het bedrijf en zijn projectenportefeuille: miljoenen klanten; maandelijkse verkopen in de miljarden. Ailoot gebruikt die operationele ervaring voor API-toegang tot AI-functies in klantproducten, agents, applicaties en automatiseringen.