Claude Code Subagents: Wat We Leerden van 18 Agents in Productie

Claude Code Subagents: Wat We Leerden van 18 Agents in Productie

Achttien Claude Code subagents leveren elke post op deze site, inclusief deze. Zes draaien op Opus, elf op Sonnet, één op Haiku. De researcher-agent alleen al heeft sinds we begonnen 74 memory-bestanden opgebouwd. Geen van allen praat met elkaar. Dat laatste verraste ons het meest: een subagent ziet nooit jouw conversatie, en ziet ook nooit de conversatie van een andere subagent. Dus is de hele pipeline in plaats daarvan opgebouwd rond bestanden op schijf. Hier is de fleet, de modelverdeling, de memory-opzet, en de dingen die onderweg stukgingen.

De korte versie:

• Een subagent draait in zijn eigen context window met zijn eigen system prompt, tools en permissions.
• Wij draaien 18 subagents: 6 op Opus, 11 op Sonnet, 1 op Haiku.
• Agents dragen werk over via bestanden op schijf, nooit via gedeelde context.
• Sinds v2.1.198 is de /agents-aanmaakwizard verdwenen. Schrijf het bestand zelf.

Wat Is een Claude Code Subagent?

Een Claude Code subagent is een gespecialiseerde assistent die draait in zijn eigen context window, met een eigen system prompt, specifieke tooltoegang en onafhankelijke permissions. Hij voert een zijtaak uit zonder je hoofdconversatie te overspoelen, en geeft alleen zijn samenvatting terug. Definities staan als Markdown-bestanden met YAML-frontmatter in .claude/agents/, gedocumenteerd in Anthropic's subagent-referentie.

Claude delegeert er automatisch aan. Het leest het description-veld van elke subagent die het kan zien, en zodra een taak matcht, draagt het het werk over zonder je eerst iets te vragen. Sinds v2.1.198 draaien die subagents standaard op de achtergrond, dus de delegatie gebeurt vaak terwijl jij blijft typen. Je kunt er ook een bij naam aanroepen als je een specifieke worker voor een specifieke taak wilt.

Drie ingebouwde subagents komen standaard mee met Claude Code: Explore voor read-only codebasezoekacties, Plan voor planningswerk, en general-purpose voor de rest.

Eén naamgevingsdetail waar oudere gidsen en oudere configbestanden over struikelen: de tool die een subagent spawnt heet Agent, niet Task. Hij werd hernoemd in v2.1.63, en de docs bevestigen dat bestaande Task(...)-verwijzingen nog steeds als alias werken. Wij gebruiken Agent doorheen deze post.

De rest hiervan is geen naslagwerk. Anthropic's docs doen dat werk al beter dan wij zouden kunnen, met zo'n 8.000 woorden en versieannotaties tot en met v2.1.212. Wat volgt is hoe achttien van deze agents eruitzien als ze elke dag draaien.

Onze Fleet van 18 Agents: Hoe een Echte Setup op Schijf Eruitziet

Onze .claude/agents/-directory bevat 18 subagent-definitiebestanden, elk een Markdown-bestand met YAML-frontmatter. Samen draaien ze de hele contentpipeline van deze site: research, briefing, schrijven, validatie, vertaling naar negen talen, beeldgeneratie en publicatie. Zes draaien op Opus, elf op Sonnet, één op Haiku.

Elke subagent-gids op de eerste pagina van Google demonstreert met hetzelfde code-reviewer-voorbeeld, rechtstreeks gekopieerd uit de docs. Hier is hoe achttien van deze agents eruitzien wanneer ze daadwerkelijk werk uitleveren.

.claude/agents/
├── abc-link-checker.md
├── brief-creator.md
├── content-gap-finder.md
├── content-refresher.md
├── content-writer.md
├── image-handler.md
├── language-translator.md
├── payload-publisher.md
├── pipeline-manager.md
├── rank-checker.md
├── rescue-diagnoser.md
├── rescue-prioritizer.md
├── researcher.md
├── sanity-publisher.md
├── seo-auditor.md
├── sitemap-checker.md
├── translation-coordinator.md
└── validator.md

Ze vallen uiteen in vier taakgroepen. Contentproductie loopt van researcher naar brief-creator naar content-writer naar validator. Distributie omvat translation-coordinator, language-translator, image-handler, payload-publisher en sanity-publisher. Onderhoud is content-refresher, rank-checker, rescue-diagnoser, rescue-prioritizer, seo-auditor, sitemap-checker en abc-link-checker. Coördinatie is pipeline-manager en content-gap-finder.

Twee van die bestanden, letterlijk gekopieerd van schijf, dragen het hele kostenargument:

# .claude/agents/researcher.md
name: researcher
tools: Read, Write, Glob, Grep, WebSearch, WebFetch, Bash
model: opus
memory: project
skills:
  - seo
  - competitor-analysis

# .claude/agents/sitemap-checker.md
name: sitemap-checker
tools: Read, Write, Edit, Glob, Grep, WebFetch
model: haiku

Zelfde mechanisme, ruwweg tien keer de kosten per token. De ene is een Opus-agent met webtoegang en persistent memory die bepaalt wat een post moet beargumenteren. De andere is een Haiku-agent die een sitemap ophaalt en een JSON-bestand schrijft. Niets in het subagent-format dwingt je om Opus-tarieven te betalen voor die tweede taak, en de meeste fleets die wij gezien hebben, doen precies dat standaard wel.

Het skills:-veld op researcher laadt bij het spawnen twee skill-definities voor in de system prompt van die subagent, en zo kent hij onze SEO-conventies zonder dat we het elke run hoeven te vertellen. Heb je er nog geen geschreven, dan behandelden we hoe je een Claude skill schrijft al apart, en deze post herhaalt dat niet.

Wil je een doorbladerbare catalogus van definities om van te kopiëren, dan is de community-verzameling awesome-claude-code-subagents degene waar mensen daadwerkelijk naar zoeken. Lees hem voor de vormen, niet voor actualiteit: sommige entries dateren van vóór de Agent-hernoeming.

Hoe Maak Je een Subagent? (De /agents-Wizard Is Verdwenen)

Je maakt een Claude Code subagent door zelf een Markdown-bestand in .claude/agents/ te schrijven, of door Claude te vragen het voor je te schrijven. Sinds v2.1.198 opent het /agents-commando niet langer de interactieve aanmaakwizard. Het uitvoeren ervan print nu alleen nog een herinnering die je naar de directory verwijst.

1. Maak het bestand aan. .claude/agents/{name}.md voor een projectsubagent die meegaat in version control, of ~/.claude/agents/{name}.md voor een subagent die je meeneemt over projecten heen.
2. Schrijf name en description. De description bepaalt meer dan al het andere in het bestand, want dat is waar Claude tegen matcht wanneer het beslist of het delegeert. Schrijf hem als een routeringsregel, niet als een functietitel.
3. Stel tools en model in. tools is een allowlist; laat je het weg, dan erft de subagent de tools van de hoofdconversatie. model overschrijft je sessiemodel.
4. Schrijf de system prompt als de Markdown-body onder de frontmatter. Subagents krijgen alleen deze prompt plus basale omgevingsdetails, niet de volledige Claude Code system prompt.
5. Roep hem aan. Automatisch, door de description te laten matchen, of expliciet door ernaar te vragen bij naam.

---
name: changelog-writer
description: Writes release notes from merged pull requests. Use when the user asks for a changelog, release notes, or a summary of what shipped.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You write release notes. Read the merged PRs since the last tag with `git log`,
group them into Added / Changed / Fixed, and write one line per change in past
tense. Never invent a change that is not in the log. Return only the markdown.

Verschillende gidsen die nu nog goed ranken, vertellen lezers nog steeds om /agents uit te voeren om de beheerinterface te openen. Die instructie is dood. Nog één addertje waar de docs expliciet over zijn: de file watcher dekt alleen directories die al bestonden toen de sessie startte, dus het eerste agentbestand in een gloednieuwe agents/-directory heeft een herstart van Claude Code nodig voordat het laadt.

Subagent vs Skill vs Agent Team vs Fork: Welke Heb Je Eigenlijk Nodig?

Kies een subagent wanneer een zijtaak je hoofdconversatie zou overspoelen en je alleen de samenvatting terug nodig hebt. Kies een skill wanneer je Claude een procedure wilt leren die hij binnen je bestaande context uitvoert. Kies een agent team wanneer workers met elkaar moeten coördineren. Kies een fork wanneer de zijtaak je conversatiegeschiedenis nodig heeft.

Subagents rapporteren aan jou en nooit aan elkaar. Agent teams sturen elkaar direct berichten. Dat ene verschil bepaalt welke primitive je nodig hebt.

Onze default is de subagent, en we hebben nooit een team nodig gehad. Coördinatie in onze pipeline is sequentieel in plaats van conversationeel, dus een gedeelde takenlijst zou niets opleveren en wel tokens kosten. Teams zijn bovendien nog experimenteel en standaard uit, wat een harde stop is voor alles wat wij onbewaakt draaien. Skills zitten op een volledig andere laag: het zijn instructies die geladen worden in welke context er ook al draait, inclusief die van een subagent, en dat is waarom researcher er twee declareert in plaats van eraan te delegeren.

Modelkeuze: Welke Agents Horen op Haiku, Sonnet en Opus

Zet model in de frontmatter van een subagent op haiku, sonnet, opus, of een specifiek model-ID, en die subagent overschrijft je sessiemodel. Onze echte verdeling over 18 agents is zes op Opus, elf op Sonnet, één op Haiku, toegewezen op basis van hoeveel oordeelsvermogen de output van de agent daadwerkelijk vereist.

Drie regels die we iedereen zouden meegeven die een fleet tiert. Zet een agent op Haiku wanneer zijn output deterministisch is en de input klein: ophalen, parsen, tellen, herformatteren. Zet een agent op Sonnet wanneer de taak lang en goed gespecificeerd is, maar iemand al besliste hoe "correct" eruitziet, wat het meeste uitvoeringswerk dekt, inclusief alle negen vertaalworkers. Bewaar Opus voor agents wier output niemand verderop in de keten nog in twijfel trekt.

Die laatste regel is waarom validator op Opus zit, ook al levert hij maar een kort rapport op. Niets controleert de controleur.

Eén versienotitie die de rekensom verandert: sinds v2.1.198 draait de ingebouwde Explore-subagent niet meer altijd op Haiku, hij erft het sessiemodel. Een user- of project-level subagent met de naam Explore overschrijft de ingebouwde versie en behoudt zijn eigen model-veld, dus definieer er een met model: haiku als je exploratie op een goedkoop model wilt houden.

File Contracts: Hoe Onze Agents Werk Overdragen Zonder Context Te Delen

Een subagent ziet je conversatiegeschiedenis niet, en ziet die van geen enkele andere subagent. In-memory overdrachten tussen agents zijn daarom structureel onmogelijk. De oplossing is elke overdracht een artefact op schijf te maken, zodat de volgende agent een bestand leest in plaats van een context te erven die hij nooit kan hebben.

techsy.community/posts/claude-code-subagents/
├── research.md      # researcher       → SERP analysis, keyword data, gaps
├── brief.md         # brief-creator    → section-by-section spec
├── en.md            # content-writer   → the post you are reading
├── de.md            # language-translator (one subagent per language)
├── hero.webp        # image-handler
├── validation.md    # validator
└── meta.json        # pipeline stage, updated by a PostToolUse hook

Vijf artefacten, elk geschreven door een andere agent, elk gelezen door de volgende, stuk voor stuk leesbaar voor een mens en getrackt in git. De pipeline overleeft contextlimieten omdat geen enkele agent ooit de context van een andere agent nodig heeft. Hij heeft alleen het bestand van de vorige agent nodig.

De duidelijkste winst is vertaling. translation-coordinator leest en.md, en spawnt vervolgens één language-translator-subagent per taal, negen of tien tegelijk. In onze repo hangt de concurrency af van het uitgeven van alle spawn-calls in één enkel bericht: dat is waargenomen gedrag op onze setup, niet iets wat de docs stellen, maar het is consistent genoeg geweest dat de coordinator er bewust voor geschreven is dat zo te doen. Elke vertaler schrijft zijn eigen {lang}.md en geen van hen kan het werk van de anderen zien, wat prima is, want het contract is het bestand en het bestand is al compleet.

Dit is ook waar subagents stoppen en iets anders begint. Subagents werken binnen één enkele sessie. Wil je écht onafhankelijke werkruimtes met hun eigen geschiedenis, dan ben je in plaats daarvan meerdere Claude Code-sessies aan het draaien, of grijp je naar isolation: worktree om één subagent zijn eigen kopie van de repository te geven.

Hoe Onthouden Subagents Dingen Tussen Sessies?

Alleen als je het memory-veld instelt, dat drie scopes accepteert: user schrijft naar ~/.claude/agent-memory/<name>/, project schrijft naar .claude/agent-memory/<name>/, en local schrijft naar .claude/agent-memory-local/<name>/. Zonder dat veld begint elke aanroep blanco. Twaalf van onze achttien agents declareren memory: project.

Na zo'n veertig posts zijn die directories aanzienlijk. researcher bevat 74 memory-bestanden, validator 66, brief-creator 65. Het zijn geen logs. Het zijn opgebouwde uitspraken: welke H1-patronen underperformden, welke claims we bij klanten niet mogen maken, welke SERP-vormen een tabel belonen boven proza.

Hier is de beperking die dit alles vormgeeft. Een memory-enabled subagent krijgt alleen de eerste 200 regels of 25KB van MEMORY.md geïnjecteerd in zijn system prompt, wat er het eerst is. Die ene limiet is waarom elk van onze agents een index bijhoudt in plaats van een dagboek.

# Researcher Memory

## Reusable post patterns
- [Challenger H1 pattern](feedback_challenger_h1_pattern.md): when a question-shaped H1 earns the click
- [Sponsored post research](feedback_sponsored_post_research.md): H1 must be category-shaped, never a review
- [Claude Skills tutorial](project_claude_skills_tutorial.md): docs own the top two slots, target the long tail

Eén regel per item, detail doorgeschoven naar het gelinkte topicbestand, dat de agent op aanvraag leest met zijn Read-tool. MEMORY.md blijft een index die binnen het injectiebudget past, terwijl het corpus erachter zonder limiet doorgroeit.

Wij gebruiken voor bijna alles project in plaats van user, omdat project-memory in de repo leeft en meereist via version control. Als een teamgenoot pullt, pullt hij het opgebouwde oordeel van de agent mee met de code. local bestaat voor de gevallen waarin je de notities wilt, maar niet de commit.

Wat Er Stukging: Faalmodi, Dubbele Namen en een Legacy Alias in Onze Eigen Repo

Vier faalmodi verklaren bijna alles wat we tegenkwamen. Een subagent die weigert te starten, een subagent die stilletjes niet degene is die je bewerkte, een subagent die Claude helemaal niet kan vinden, en een harde sessieceiling op hoeveel je kunt spawnen. Alle vier hebben korte, ondubbelzinnige fixes.

Die met de dubbele naam is vervelender dan hij leest. Je bewerkt een bestand, het gedrag verandert niet, en er is nergens een foutmelding, want een ander bestand met dezelfde name won de leesvolgorde.

Hooks hielpen meer dan we verwachtten bij de fouten die helemaal geen fouten zijn, gewoon stappen die een mens vergeet. Die van ons is bewust dom:

"SubagentStop": [
  {
    "matcher": "content-writer",
    "hooks": [
      {
        "type": "command",
        "command": "echo 'Content writer finished. Run /validate to check quality and SEO compliance.'"
      }
    ]
  }
]

Nu de eerlijke. Terwijl we deze post schreven, grepten we onze eigen fleet en vonden dit nog steeds in translation-coordinator.md staan:

# .claude/agents/translation-coordinator.md
name: translation-coordinator
tools: Read, Write, Glob, Grep, Task
model: sonnet

Task, niet Agent. Dat veld is verouderd sinds v2.1.63 en heeft nog nooit gefaald, omdat Anthropic de alias behield. We hebben het nog niet opgeruimd. Als je eigen agentbestanden nog Task zeggen, zijn ze niet kapot, alleen oud, en de alias doet momenteel stilletjes zijn werk voor een hoop repo's.

Eén correctie in de andere richting: gidsen geschreven vóór v2.1.172 vertellen lezers dat een subagent geen subagents kan spawnen. Dat kan wel, en al sinds die release. De diepte is vastgezet op vijf niveaus onder de hoofdconversatie en niet configureerbaar, dus een subagent op diepte vijf krijgt simpelweg de Agent-tool niet.

Wat Subagents Kosten, en Wanneer Je Er Geen Moet Gebruiken

Elke subagent-spawn creëert een vers context window, dus delegatie is nooit gratis. Anthropic's engineeringteam rapporteert dat agents ruwweg 4x meer tokens gebruiken dan chatinteracties en multi-agentsystemen ruwweg 15x meer, en dat tokengebruik alleen al 80% van de gemeten performance-variantie verklaart.

Wij hebben geen eigen tokenmetingen om aan toe te voegen, dus behandel elke specifieke multiplier die je over dit onderwerp leest, inclusief de 4x-tot-7x-cijfers die rondzweven in andere blogposts, als het getal van die auteur, niet als een benchmark. Anthropic's schrijfstuk over het multi-agent research system is hier de enige bron met echte data erachter, en diezelfde studie vond dat een Opus lead agent met Sonnet-subagents een enkele Opus-agent met 90,2% versloeg op hun interne evaluatie. Dat resultaat, niet het tokenaantal, is het argument voor tiering.

Sla de subagent over wanneer de output toch in je hoofdconversatie thuishoort, want dan plak je hem er alsnog in terug en betaal je dubbel. Sla hem over voor kleine edits waarbij de delegatie-rondrit meer kost dan het werk zelf. En sla hem over wanneer de taak écht je conversatiegeschiedenis nodig heeft: gebruik dan een fork, die de volledige conversatie erft en de prompt cache van de ouder hergebruikt, wat hem goedkoper maakt dan een verse subagent voor contextzwaar zijwerk. Anthropic's eigen kostenrichtlijn en hun when-to-use-framing komen allebei op hetzelfde punt uit.

De cap van 200 per sessie is de moeite waard om te kennen voordat je een fan-out ontwerpt. Het is een echt plafond op ongebreidelde delegatie, en hem verhogen is een bewuste handeling, geen default.

Over de auteur

Mert Batur bouwt bij Techsy, waar het team AI agents, automation-systemen en voice/SDR-pipelines voor B2B-klanten uitlevert. Hij schrijft over de LLM tooling stack en de Claude Skills die het Techsy-team daadwerkelijk in productie gebruikt.

Techsy — University of Birmingham · LinkedIn

Veelgestelde vragen

Wat zijn Claude Code subagents?

Claude Code subagents zijn gespecialiseerde assistenten die elk in hun eigen context window draaien, met een eigen system prompt, beperkte tooltoegang en onafhankelijke permissions. Je definieert er een als Markdown-bestand met YAML-frontmatter in .claude/agents/. De subagent voert een zijtaak uit en geeft alleen zijn samenvatting terug aan je hoofdconversatie.

Gebruikt Claude Code subagents automatisch?

Ja. Claude leest het description-veld van elke subagent die het ter beschikking heeft en delegeert zodra een taak matcht, zonder je eerst iets te vragen. Sinds v2.1.198 draaien subagents standaard op de achtergrond, dus het gedelegeerde werk gebeurt vaak terwijl jij blijft typen in de hoofdconversatie.

Waar staan subagent-bestanden?

Projectsubagents staan in .claude/agents/ en usersubagents in ~/.claude/agents/. Beide locaties worden recursief gescand, dus submappen zijn geen probleem. Identiteit komt alleen van het name-frontmatterveld, nooit van het pad. Managed subagents die door een beheerder zijn uitgerold, gaan vóór project- en userdefinities met dezelfde naam.

Hoe roep ik een subagent expliciet aan?

Vraag ernaar bij naam in je prompt, bijvoorbeeld "gebruik de validator-subagent op dit concept." Expliciete aanroep omzeilt de description-matching die automatische delegatie aandrijft, wat helpt wanneer twee van je subagents overlappende descriptions hebben en Claude steeds naar de verkeerde grijpt.

Kan een subagent zijn eigen subagents spawnen?

Ja, sinds Claude Code v2.1.172. Gidsen geschreven vóór die release stellen dat nesten onmogelijk is, en die zijn verouderd. Diepte telt niveaus onder de hoofdconversatie en is vastgezet op vijf: een subagent op diepte vijf krijgt de Agent-tool niet. De limiet is niet configureerbaar.

Onthouden subagents iets tussen sessies?

Alleen als je het memory-veld instelt. Dat accepteert user voor ~/.claude/agent-memory/<name>/, project voor .claude/agent-memory/<name>/, of local voor .claude/agent-memory-local/<name>/. Zonder dat veld begint elke aanroep blanco. Twaalf van onze achttien agents gebruiken memory: project zodat hun notities meereizen in version control.

Kan een subagent een ander model gebruiken dan mijn sessie?

Ja. Zet model in de frontmatter op haiku, sonnet, opus, of een specifiek model-ID, en het overschrijft je sessiemodel voor die subagent. Onze fleet splitst zes op Opus, elf op Sonnet, en één op Haiku, toegewezen op basis van hoeveel oordeelsvermogen de output van elke agent vereist.

Waarom verschijnt mijn nieuwe subagent niet?

Drie gebruikelijke oorzaken. De agents-directory bestond nog niet toen de sessie startte, dus de watcher pikte hem nooit op: herstart Claude Code. Of twee bestanden delen dezelfde name en er laadt er maar één. Of niets in je tools-lijst lost op, wat sinds v2.1.208 weigert te starten met een foutmelding die de naam noemt.

Is Task nog een geldige toolnaam?

Ja, als alias. De Task-tool werd hernoemd naar Agent in v2.1.63, en bestaande Task(...)-verwijzingen werken nog steeds in settings en agentdefinities. Schrijf Agent in nieuwe bestanden. Ons eigen translation-coordinator.md declareert nog steeds Task, wat we tegenkwamen terwijl we deze post schreven en nog niet hebben opgeruimd.

Drie Dingen om Te Onthouden

Bouw je je eerste fleet op, begin dan hier. Het description-veld bepaalt alles, want dat is wat Claude leest bij het kiezen van een worker, dus schrijf hem als een routeringsregel, niet als een functietitel. Ontwerp de overdracht als bestand voordat je de agent ontwerpt, want geen enkele subagent zal ooit de context van een ander zien. En zet elke agent op het goedkoopste model dat een correct antwoord kan produceren, en verhoog het pas zodra je hem op een fout betrapt.

Ontdek de volledige library voor de specs achter deze pipeline.