Marktmannen wiki Coderen met AI

Subagents

Laatst bijgewerkt: 15-06-2026

TL;DR: Subagents zijn losse markdown-bestanden met YAML-frontmatter die werken als specialisten met een schone context — gebruik ze voor research, herhaalde taken en parallel werk, niet voor elke kleine vraag.

Een subagent is een gespecialiseerde AI-assistent die een specifieke taak uitvoert in zijn eigen, geïsoleerde contextvenster. De hoofdsessie is de orchestrator: die delegeert werk, krijgt alleen een samenvatting terug, en blijft zelf schoon.

Wat is een subagent?

Net als een skill is een subagent niets anders dan een markdown-bestand met YAML-frontmatter en een instructietekst. Het verschil zit niet in het formaat, maar in hoe het draait:

Skill Subagent
Context Deelt het hoofdvenster Eigen, schoon contextvenster
Parallel? Nee — draait inline in de hoofdsessie Ja — meerdere tegelijk mogelijk
Model Zelfde als hoofdsessie Kan afwijken (bijv. Haiku voor research)
Geheugen Geen apart geheugen Optioneel persistent (memory: user/project/local)

Subagents en skills zijn geen concurrenten: subagents kunnen skills aanroepen, en skills kunnen subagents aanroepen (maar subagents kunnen geen andere subagents spawnen — geen oneindige nesting).

Eenvoudige vuistregel: een skill is wat Claude weet te doen; een subagent is wie het werk doet. Een rol is in feite gewoon context die op een specifieke taak wordt toegepast — en een skill is daarmee een "subagent zonder rol". De rol komt via CLAUDE.md/de subagent-frontmatter, de taak via SKILL.md. Vuistregel voor de keuze: isoleer je de context (overbodige ruis weg uit de hoofdsessie) → subagent; heb je de tussenresultaten terug nodig in de hoofdsessie → skill.

Ingebouwde vs. aangepaste subagents

Claude Code levert drie ingebouwde subagents mee:

Subagent Model Tools Doel
Explore Haiku Alleen-lezen Snel codebase doorzoeken, slaat CLAUDE.md/git-status over
Plan Erft van hoofdsessie Alleen-lezen Onderzoek tijdens plan mode
general-purpose Erft van hoofdsessie Alle tools Complexe multi-step taken met zowel onderzoek als wijzigingen

Wanneer je in een demo "5 sub-agents met verschillende persona's" ziet spinnen, zijn dat vaak gewoon general-purpose agents met verschillende prompts — geen aparte custom-bestanden.

Een aangepaste subagent maak je zelf als markdown-bestand:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Progressive disclosure: de rol van description

Claude leest bij elke prompt alleen de name + description van alle beschikbare subagents (en skills) om te beslissen of er één relevant is. Pas als een subagent matcht, wordt de volledige body geladen.

Daarom is de description het belangrijkste veld: - Wees precies over wanneer wel triggeren ("gebruik proactief na elke codewijziging") - Wees precies over wanneer niet triggeren - Misfires (verkeerd of niet getriggerd) los je op door te itereren: test, kijk waarom het wel/niet vuurde, scherp de description aan

Een veelgemaakte fout: een open YAML-quote vergeten sluiten — dat breekt de hele frontmatter en dus de trigger-detectie.

Project vs. globale scope

Locatie Scope Gebruik voor
.claude/agents/ Huidig project Subagents specifiek voor deze codebase, deelbaar via versiebeheer
~/.claude/agents/ Alle projecten Persoonlijke subagents die je overal wilt gebruiken
Plugin's agents/-map Waar plugin actief is Gedeeld via plugins

Bij /agents kun je kiezen tussen generate with Claude (beschrijf wat de subagent moet doen, Claude bouwt de YAML) of handmatige configuratie. Bij "generate with Claude" wordt de description vaak te lang — knip die terug tot het strikt noodzakelijke (progressive disclosure).

Wanneer wel, wanneer niet

Gebruik een subagent als: - De taak een berg output produceert die je daarna nooit meer leest (logs, research, file dumps) - Je veel bestanden moet doorlezen of een wall of output verwacht - Het een herhaalde job is — bouw er een custom subagent voor - Het werk onafhankelijk en parallelliseerbaar is (bijv. 15 hoofdstukken tegelijk reviewen) - Je een onbevooroordeelde reviewer wilt — een subagent wordt wakker zonder geheugen of context - Je geld wilt besparen: laat een goedkoop model (Haiku) een rapport samenvatten terwijl je zelf op Opus werkt

Gebruik geen subagent als: - Het een snelle, kleine wijziging is - Stappen van elkaar afhankelijk zijn (1→2→3→4) — dan eerder een agent team of gewoon de hoofdsessie - De subagent de volledige conversatiecontext nodig heeft - De subagent een vraag aan jou moet stellen (subagents kunnen niet met de gebruiker praten — alleen met de orchestrator)

Subagents vs. agent teams vs. dynamic workflows

Subagents Agent teams Dynamic workflows
Communicatie Alleen 1-op-1 met hoofdsessie, niet onderling Teamleden praten/debatteren met elkaar Hoofdsessie delegeert aan veel subagents tegelijk
Relatie 1-op-1 1-op-veel met onderlinge links 1-op-veel, parallel
Kosten Gematigd Hoger (onderlinge communicatie) Hoog — kan tientallen tot 200+ agents spawnen
Gebruik Geïsoleerd, parallel werk Debatten, panel-reviews, meerdere persona's Grote, ambitieuze taken in één keer

Sinds Opus 4.8 bestaan dynamic workflows: de hoofdsessie spint zelf tientallen subagents op tegelijk. Trigger-woord verschoof van "workflow" naar "ultra code" om onbedoelde activatie te voorkomen — wees voorzichtig, dit kan snel je sessielimiet opeten (in extreme tests: 210 subagents tegelijk).

Belangrijkste frontmatter-velden

Veld Verplicht Functie
name Ja Unieke identifier (lowercase, hyphens)
description Ja Bepaalt wanneer Claude delegeert — zie progressive disclosure hierboven
tools / disallowedTools Nee Allowlist resp. denylist van tools — bijv. read-only maken door Write/Edit te weigeren
model Nee sonnet, opus, haiku, fable, volledige model-ID, of inherit (default)
maxTurns Nee Hard plafond tegen oneindige onderzoeksloops
memory Nee user / project / local — persistent geheugen dat per sessie meegroeit
permissionMode Nee default, acceptEdits, auto, plan, bypassPermissions, etc.
isolation: worktree Nee Geeft de subagent een eigen git worktree, automatisch opgeruimd zonder wijzigingen
skills Nee Preload volledige skill-content bij opstart van de subagent
hooks Nee PreToolUse/PostToolUse/Stop — bijv. een hook die alleen SELECT-queries toestaat

Persistent memory: subagents die leren

Met memory: project krijgt een subagent een eigen map (.claude/agent-memory/<naam>/) die over sessies heen bewaard blijft. De subagent leest en schrijft zelf naar MEMORY.md (max 200 regels / 25KB, daarna curateert hij zelf). Praktisch: - Vraag de subagent vóór een taak: "check je memory voor patronen die je eerder zag" - Vraag na afloop: "sla op wat je hebt geleerd"

Dit bouwt institutionele kennis op — vergelijkbaar met de cross-sessie laag in Geheugen en Context, maar dan per subagent in plaats van projectbreed.

Veiligheid: subagents van anderen

Net als bij skills van derden (zie Hermes Agent › Kritische blik: zelf bouwen vs. Hermes overnemen) geldt: een subagent is "gewoon een markdown-bestand" — dus eenvoudig te delen, maar ook eenvoudig om een prompt-injectie in te verstoppen. Praktisch advies uit de bron: laat een read-only verificatie-subagent geïmporteerde subagent-bestanden controleren op verdachte instructies vóórdat je ze gebruikt.

Verwante concepten

Bronnen

#agents #architectuur #context

Backlinks