Marktmannen wiki Coderen met AI

Subagents

Laatst bijgewerkt

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. Subagents kunnen ook zelf subagents starten, standaard tot 3 lagen onder de hoofdsessie (sinds v2.1.219; v2.1.172–216: 5 lagen). Instelbaar via CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (1 = uit); per subagent uit te sluiten via tools/disallowedTools. Er draaien maximaal 20 subagents tegelijk (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS).

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 hoofd-subagents mee:

Subagent Model Tools Doel
Explore Sessiemodel (niet standaard 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

Daarnaast zijn er helpers: claude (catch-all), statusline-setup en claude-code-guide. Wil je Explore toch op Haiku, maak dan een eigen Explore-subagent met model: haiku.

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

Volledig zijn er vijf scopes: managed (organisatie), de --agents-flag (JSON, v2.1.281+), project, user en plugin.

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 — tot 1.000 agents per run
Gebruik Geïsoleerd, parallel werk Debatten, panel-reviews, meerdere persona's Grote, ambitieuze taken in één keer

Agent teams zijn experimenteel en staan standaard uit (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, in settings of als omgevingsvariabele); geneste teams kunnen niet.

Bij dynamic workflows orkestreert een JS-script subagents: standaard 16 agents tegelijk (instelbaar tot 256), max 1.000 agents per run. Starten doe je met het keyword ultracode (één woord) of /effort ultracode — Claude plant dan per substantiële taak een workflow — of door in eigen woorden te vragen om een workflow ("use a workflow"). Wees voorzichtig, dit kan snel je sessielimiet opeten (volgens de bron in extreme tests 210 subagents tegelijk; dat getal staat niet in de docs). Zie Dynamic Workflows.

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. Volgorde: per-aanroep-parameter (v2.1.292+) → frontmatter → CLAUDE_CODE_SUBAGENT_MODEL → hoofdmodel
maxTurns Nee Hard plafond tegen oneindige onderzoeksloops
memory Nee user / project / local — persistent geheugen dat per sessie meegroeit
permissionMode Nee default, acceptEdits, auto, dontAsk, bypassPermissions, plan (+ alias manual). Genegeerd als de hoofdsessie in bypass/acceptEdits/auto staat, en bij plugin-subagents
isolation: worktree Nee Geeft de subagent een eigen git worktree (branch vanaf de default branch), automatisch opgeruimd zonder wijzigingen
skills Nee Preload volledige skill-content bij opstart van de subagent (max 32; niet bij disable-model-invocation: true)
hooks Nee PreToolUse/PostToolUse/Stop — bijv. een hook die alleen SELECT-queries toestaat (genegeerd bij plugin-subagents)
effort, background, omitClaudeMd, mcpServers, color, initialPrompt Nee Nieuwere velden (o.a. effort, achtergrondgedrag, CLAUDE.md overslaan, MCP-servers); details in de officiële docs

Achtergrond als default: sinds v2.1.198 draaien subagents standaard op de achtergrond (fork mode, /subtask, background: true).

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

  • Expert-Kloon via Zelfverbeterende Wiki — concreet voorbeeld van een Stop-hook die verplicht laat testen vóór een subagent "klaar" mag zeggen, plus een subagent+skill-split om de denkwijze van een expert te klonen
  • Skills en Plugins — subagents en skills delen hetzelfde markdown+YAML-formaat en progressive disclosure
  • Skill Systems — orchestrator-skills die subagents aansturen voor parallelle stappen
  • Agentic OS — subagents als bouwsteen van de bredere agent-architectuur
  • Anthropic Werkpatronen voor Niet-technici — het marketingteam-voorbeeld met twee gespecialiseerde sub-agents (headlines vs. beschrijvingen)
  • Geheugen en Context — persistent subagent-memory als aanvulling op de vier geheugenlagen
  • Van Plannen naar Checks — nieuwe nuance op agent teams: Claude bepaalt zelf de teamgrootte binnen een door de gebruiker gezet plafond, in plaats van een vooraf handmatig samengesteld team

Bronnen

#agents #context

Backlinks