Claude Code Subagents: Vad vi lärde oss av att köra 18 av dem i produktion

Claude Code Subagents: Vad vi lärde oss av att köra 18 av dem i produktion

Arton Claude Code-subagents levererar varje inlägg på den här sajten, inklusive det här. Sex kör på Opus, elva på Sonnet, en på Haiku. Researcher-agenten har ensam samlat på sig 74 minnesfiler sedan vi började. Ingen av dem pratar med varandra. Det var den delen som förvånade oss mest: en subagent ser aldrig din konversation, och den ser aldrig en annan subagents konversation heller. Så hela pipelinen är istället byggd kring filer på disk. Här är flottan, modellfördelningen, minnesuppsättningen och det som gick sönder på vägen.

Kortversionen:

• En subagent körs i sitt eget kontextfönster med sin egen systemprompt, egna verktyg och egna behörigheter.
• Vi kör 18 subagents: 6 på Opus, 11 på Sonnet, 1 på Haiku.
• Agenter lämnar över arbete via filer på disk, aldrig via delad kontext.
• Sedan v2.1.198 är /agents-guiden för att skapa agenter borta. Skriv filen själv.

Vad är en Claude Code-subagent?

En Claude Code-subagent är en specialiserad assistent som körs i sitt eget kontextfönster med en egen systemprompt, specifik verktygsåtkomst och oberoende behörigheter. Den utför en sidouppgift utan att svämma över din huvudkonversation, och returnerar sedan bara sin sammanfattning. Definitionerna lever som Markdown-filer med YAML-frontmatter i .claude/agents/, dokumenterat i Anthropics referens för subagents.

Claude delegerar till en automatiskt. Den läser description-fältet på varje subagent den kan se, och när en uppgift matchar lämnar den över arbetet utan att fråga dig först. Sedan v2.1.198 körs dessa subagents i bakgrunden som standard, så delegeringen sker ofta medan du fortsätter skriva. Du kan också anropa en vid namn när du vill ha en specifik arbetare på ett specifikt jobb.

Tre inbyggda följer med Claude Code: Explore för skrivskyddad kodbassökning, Plan för planeringsarbete och general-purpose för allt annat.

En namndetalj som ställer till det för äldre guider och äldre konfigurationsfiler: verktyget som startar en subagent heter Agent, inte Task. Det döptes om i v2.1.63, och dokumentationen bekräftar att befintliga Task(...)-referenser fortfarande fungerar som alias. Vi använder Agent genomgående i det här inlägget.

Resten av det här är ingen referens. Anthropics dokumentation gör redan det jobbet bättre än vi kan, på ungefär 8 000 ord med versionsnoteringar ner till v2.1.212. Det som följer är hur arton av dessa ser ut när de körs varje dag.

Vår flotta på 18 agenter: så ser en verklig uppsättning ut på disk

Vår katalog .claude/agents/ innehåller 18 definitionsfiler för subagents, var och en en Markdown-fil med YAML-frontmatter. Tillsammans kör de hela innehållspipelinen för den här sajten: research, briefing, skrivande, validering, översättning till nio språk, bildgenerering och publicering. Sex kör på Opus, elva på Sonnet, en på Haiku.

Varje guide om subagents på Googles första sida demonstrerar med samma code-reviewer-exempel kopierat rakt ur dokumentationen. Här är hur arton av dem ser ut när de faktiskt levererar arbete.

.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

De grupperas i fyra jobb. Innehållsproduktion går från researcher till brief-creator till content-writer till validator. Distribution täcker translation-coordinator, language-translator, image-handler, payload-publisher och sanity-publisher. Underhåll är content-refresher, rank-checker, rescue-diagnoser, rescue-prioritizer, seo-auditor, sitemap-checker och abc-link-checker. Koordinering är pipeline-manager och content-gap-finder.

Två av de här filerna, kopierade ordagrant från disk, bär hela kostnadsargumentet:

# .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

Samma mekanism, ungefär tio gånger kostnaden per token. Den ena är en Opus-agent med webbåtkomst och beständigt minne som avgör vad ett inlägg ska argumentera för. Den andra är en Haiku-agent som hämtar en sitemap och skriver en JSON-fil. Inget i subagent-formatet tvingar dig att betala Opus-priser för det andra jobbet, och de flesta flottor vi har sett gör precis det som standard.

skills:-fältet på researcher laddar in två skill-definitioner i den subagentens systemprompt redan vid start, vilket är hur den känner till våra SEO-konventioner utan att bli tillsagd varje körning. Om du inte har skrivit en själv än har vi gått igenom hur du skriver en Claude-skill separat, och det här inlägget upprepar inte det.

Om du vill ha en genomsökningsbar katalog med definitioner att kopiera från är community-samlingen awesome-claude-code-subagents den folk faktiskt söker efter. Läs den för formerna, inte för aktualiteten: vissa poster är från innan Agent-namnbytet.

Hur skapar du en subagent? (/agents-guiden är borta)

Du skapar en Claude Code-subagent genom att själv skriva en Markdown-fil i .claude/agents/, eller genom att be Claude skriva den åt dig. Sedan v2.1.198 öppnar /agents-kommandot inte längre den interaktiva skapandeguiden. Att köra det nu skriver bara ut en påminnelse som pekar dig mot katalogen.

1. Skapa filen. .claude/agents/{name}.md för en projektsubagent som checkas in i versionskontroll, eller ~/.claude/agents/{name}.md för en som följer dig mellan projekt.
2. Skriv name och description. description avgör mer än något annat i filen, eftersom det är den Claude matchar mot när den väljer om den ska delegera. Skriv den som en routningsregel, inte en jobbtitel.
3. Sätt tools och model. tools är en allowlist; utelämnar du den ärver subagenten huvudkonversationens verktyg. model överstyr din sessionsmodell.
4. Skriv systemprompten som Markdown-bodyn under frontmattern. Subagents får bara den här prompten plus grundläggande miljödetaljer, inte hela Claude Codes systemprompt.
5. Anropa den. Automatiskt, genom att låta description matcha, eller explicit genom att be om den vid namn.

---
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.

Flera guider som fortfarande rankar högt idag säger åt läsare att köra /agents för att öppna hanteringsgränssnittet. Den instruktionen är död. Ytterligare en fälla dokumentationen är tydlig med: filbevakaren täcker bara kataloger som fanns när sessionen startade, så den första agentfilen i en helt ny agents/-katalog behöver en omstart av Claude Code innan den laddas.

Subagent vs skill vs agent team vs fork: vilken behöver du egentligen?

Välj en subagent när en sidouppgift skulle svämma över din huvudkonversation och du bara behöver sammanfattningen tillbaka. Välj en skill när du vill lära Claude en procedur den kör inne i din befintliga kontext. Välj ett agent team när arbetare måste samordna sig med varandra. Välj en fork när sidouppgiften behöver din konversationshistorik.

Subagents rapporterar till dig och aldrig till varandra. Agent teams meddelar varandra direkt. Den skillnaden ensam avgör vilken primitiv du behöver.

Vårt default är subagenten, och vi har aldrig behövt ett team. Koordinering i vår pipeline är sekventiell snarare än konversationsdriven, så en delad tasklista skulle inte ge något och bara kosta tokens. Teams är dessutom fortfarande experimentella och avstängda som standard, vilket är stopp för allt vi kör obevakat. Skills sitter på ett helt annat lager: de är instruktioner som laddas in i vilken kontext som helst som redan körs, inklusive en subagents, vilket är varför researcher deklarerar två av dem istället för att delegera till dem.

Modellval: vilka agenter hör hemma på Haiku, Sonnet och Opus

Sätt model i en subagents frontmatter till haiku, sonnet, opus, eller ett specifikt modell-ID, så överstyr den subagenten din sessionsmodell. Vår faktiska fördelning över 18 agenter är sex på Opus, elva på Sonnet, en på Haiku, tilldelad efter hur mycket omdöme agentens output faktiskt kräver.

Tre regler vi skulle ge vidare till vem som helst som ska nivåindela en flotta. Sätt en agent på Haiku när dess output är deterministisk och dess input är liten: hämtning, parsning, räkning, omformatering. Sätt en agent på Sonnet när uppgiften är lång och väl specificerad men någon redan har bestämt hur ett "korrekt" svar ser ut, vilket täcker det mesta av utförandearbetet inklusive alla nio översättningsarbetare. Spara Opus till agenter vars output ingenting nedströms kommer att ifrågasätta.

Den sista regeln är varför validator sitter på Opus trots att den producerar en kort rapport. Ingenting kontrollerar kontrollanten.

En versionsdetalj som ändrar räkningen: sedan v2.1.198 kör den inbyggda Explore-subagenten inte längre alltid på Haiku, den ärver sessionsmodellen. En subagent på användar- eller projektnivå som heter Explore överstyr den inbyggda och behåller sitt eget model-fält, så definiera en med model: haiku om du vill hålla utforskning på en billig modell.

Filkontrakt: hur våra agenter lämnar över arbete utan att dela kontext

En subagent ser inte din konversationshistorik, och den ser inte någon annan subagents heller. Överlämningar i minnet mellan agenter är därför strukturellt omöjliga. Lösningen är att göra varje överlämning till en artefakt på disk, så att nästa agent läser en fil istället för att ärva en kontext den aldrig kan ha.

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

Fem artefakter, var och en skriven av en annan agent, var och en läst av nästa, alla läsbara för en människa och versionshanterade i git. Pipelinen överlever kontextgränser eftersom ingen agent någonsin behöver en annan agents kontext. Den behöver bara föregående agents fil.

Den tydligaste vinsten är översättning. translation-coordinator läser en.md, och startar sedan en language-translator-subagent per språk, nio eller tio stycken samtidigt. I vårt repo beror samtidigheten på att alla startanropen skickas i ett och samma meddelande: det är observerat beteende i vår uppsättning snarare än något dokumentationen slår fast, men det har varit tillräckligt konsekvent för att koordinatorn är skriven för att göra det med flit. Varje översättare skriver sin egen {lang}.md och ingen av dem kan se de andras arbete, vilket är okej, eftersom kontraktet är filen och filen redan är komplett.

Det här är också där subagents slutar och något annat tar vid. Subagents jobbar inom en enda session. Om du vill ha genuint oberoende arbetsytor med sina egna historiker kör du flera Claude Code-sessioner istället, eller griper efter isolation: worktree för att ge en subagent sin egen kopia av repot.

Kommer subagents ihåg saker mellan sessioner?

Bara om du sätter memory-fältet, som tar tre scope: user skriver till ~/.claude/agent-memory/<name>/, project skriver till .claude/agent-memory/<name>/, och local skriver till .claude/agent-memory-local/<name>/. Utan det börjar varje anrop blankt. Tolv av våra arton agenter deklarerar memory: project.

Efter ungefär fyrtio inlägg är de här katalogerna substantiella. researcher har 74 minnesfiler, validator 66, brief-creator 65. De är inga loggar. De är ackumulerade avgöranden: vilka H1-mönster som underpresterade, vilka kundpåståenden vi inte får göra, vilka SERP-former som belönar en tabell framför löptext.

Här är begränsningen som formar allt detta. En minnesaktiverad subagent får bara de första 200 raderna eller 25 KB av MEMORY.md injicerade i sin systemprompt, vilket som kommer först. Den enda gränsen är varför var och en av våra agenter håller ett index istället för en journal.

# 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

En rad per post, detaljerna skjutna in i den länkade ämnesfilen, som agenten läser vid behov med sitt Read-verktyg. MEMORY.md förblir ett index som ryms inom injektionsbudgeten medan korpusen bakom den växer utan gräns.

Vi använder project snarare än user för nästan allt, eftersom projektminnet lever i repot och följer med genom versionskontroll. När en kollega gör pull får de agentens ackumulerade omdöme på köpet med koden. local finns för de fall där du vill ha anteckningarna men inte committen.

Det som gick sönder: felmönster, dubblettnamn och ett gammalt alias i vårt eget repo

Fyra felmönster står för nästan allt vi har stött på. En subagent som vägrar starta, en subagent som tyst inte är den du redigerade, en subagent Claude inte hittar alls, och ett hårt sessionstak för hur många du kan starta. Alla fyra har korta, entydiga fixar.

Dubblettnamn-felet är otäckare än det låter. Du redigerar en fil, beteendet ändras inte, och det finns inget fel någonstans, eftersom en annan fil med samma name vann läsordningen.

Hooks hjälpte mer än vi förväntade oss för de fel som inte alls är fel, bara steg en människa glömmer. Vår är avsiktligt enkel:

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

Nu den ärliga biten. Medan vi skrev det här inlägget grepade vi vår egen flotta och hittade det här som fortfarande låg kvar i translation-coordinator.md:

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

Task, inte Agent. Det fältet har varit inaktuellt sedan v2.1.63 och det har aldrig en enda gång fallerat, eftersom Anthropic behöll aliaset. Vi har inte städat upp det än. Om dina egna agentfiler fortfarande säger Task är de inte trasiga, de är bara gamla, och aliaset gör ett tyst jobb för väldigt många repon just nu.

En rättelse åt andra hållet: guider skrivna före v2.1.172 säger till läsare att en subagent inte kan starta subagents. Det kan den, och har kunnat sedan den releasen. Djupet är fast på fem nivåer under huvudkonversationen och går inte att konfigurera, så en subagent på djup fem får helt enkelt inte Agent-verktyget.

Vad subagents kostar, och när du inte ska använda en

Varje gång en subagent startas skapas ett nytt kontextfönster, så delegering är aldrig gratis. Anthropics engineering-team rapporterar att agenter använder ungefär 4x fler tokens än chattinteraktioner och multiagentsystem ungefär 15x fler, och att enbart tokenanvändning förklarar 80 % av prestandavariansen de mätte.

Vi har inga egna tokenmätningar att lägga till, så behandla varje specifik multiplikator du läser om det här ämnet, inklusive 4x-till-7x-siffrorna som flyter runt i andra blogginlägg, som den författarens siffra snarare än ett riktmärke. Anthropics genomgång av multiagent-forskningssystemet är den enda källan här med riktig data bakom sig, och samma studie fann att en Opus-ledaragent med Sonnet-subagents slog en ensam Opus-agent med 90,2 % i deras interna utvärdering. Det resultatet, inte tokenräkningen, är argumentet för nivåindelning.

Hoppa över subagenten när outputen ändå hör hemma i din huvudkonversation, för då klistrar du bara in den igen och betalar dubbelt. Hoppa över den för små ändringar där tur-och-retur för delegeringen kostar mer än att göra jobbet själv. Och hoppa över den när uppgiften genuint behöver din konversationshistorik: använd en fork istället, som ärver hela konversationen och återanvänder förälderns prompt-cache, vilket gör den billigare än en ny subagent för kontexttungt sidoarbete. Anthropics egen kostnadsvägledning och deras ramverk för när du ska använda vad landar båda på samma ställe.

Taket på 200 per session är värt att känna till innan du designar en fan-out. Det är ett verkligt tak mot skenande delegering, och att höja det är en medveten handling snarare än ett default.

Om författaren

Mert Batur bygger på Techsy, där teamet levererar AI-agenter, automationssystem och voice/SDR-pipelines till B2B-kunder. Han skriver om LLM-tooling-stacken och de Claude Skills som Techsy-teamet faktiskt använder i produktion.

Techsy — University of Birmingham · LinkedIn

Vanliga frågor

Vad är Claude Code-subagents?

Claude Code-subagents är specialiserade assistenter som var och en körs i sitt eget kontextfönster med en egen systemprompt, begränsad verktygsåtkomst och oberoende behörigheter. Du definierar en som en Markdown-fil med YAML-frontmatter i .claude/agents/. Subagenten utför en sidouppgift och returnerar bara sin sammanfattning till din huvudkonversation.

Använder Claude Code subagents automatiskt?

Ja. Claude läser description-fältet för varje subagent den har tillgång till och delegerar när en uppgift matchar, utan att fråga dig först. Sedan v2.1.198 körs subagents i bakgrunden som standard, så det delegerade arbetet sker ofta medan du fortsätter skriva i huvudkonversationen.

Var ligger subagent-filerna?

Projektsubagents ligger i .claude/agents/ och användarsubagents i ~/.claude/agents/. Båda platserna skannas rekursivt, så undermappar fungerar utan problem. Identiteten kommer bara från name-fältet i frontmattern, aldrig från sökvägen. Hanterade subagents som driftsatts av en administratör går före projekt- och användardefinitioner som delar samma namn.

Hur anropar jag en subagent explicit?

Be om den vid namn i din prompt, till exempel "använd validator-subagenten på det här utkastet". Explicit anrop går förbi den description-matchning som driver automatisk delegering, vilket hjälper när två av dina subagents har överlappande descriptions och Claude fortsätter gripa efter fel en.

Kan en subagent starta sina egna subagents?

Ja, sedan Claude Code v2.1.172. Guider skrivna före den releasen påstår att nästling är omöjligt, och de är föråldrade. Djupet räknar nivåer under huvudkonversationen och är fast på fem: en subagent på djup fem får inte Agent-verktyget. Gränsen går inte att konfigurera.

Kommer subagents ihåg något mellan sessioner?

Bara om du sätter memory-fältet. Det accepterar user för ~/.claude/agent-memory/<name>/, project för .claude/agent-memory/<name>/, eller local för .claude/agent-memory-local/<name>/. Utan det börjar varje anrop blankt. Tolv av våra arton agenter använder memory: project så att deras anteckningar följer med i versionskontroll.

Kan en subagent använda en annan modell än min session?

Ja. Sätt model i frontmattern till haiku, sonnet, opus, eller ett specifikt modell-ID, så överstyr det din sessionsmodell för den subagenten. Vår flotta delas i sex på Opus, elva på Sonnet och en på Haiku, tilldelad efter hur mycket omdöme varje agents output kräver.

Varför dyker inte min nya subagent upp?

Tre vanliga orsaker. agents-katalogen fanns inte när sessionen startade, så bevakaren fångade den aldrig: starta om Claude Code. Eller så delar två filer samma name och bara en laddas. Eller så går inget i din tools-lista att matcha, vilket sedan v2.1.208 vägrar starta med ett namngivet felmeddelande.

Är Task fortfarande ett giltigt verktygsnamn?

Ja, som ett alias. Task-verktyget döptes om till Agent i v2.1.63, och befintliga Task(...)-referenser fungerar fortfarande i inställningar och agentdefinitioner. Skriv Agent i nya filer. Vår egen translation-coordinator.md deklarerar fortfarande Task, vilket vi upptäckte medan vi skrev det här inlägget och inte har städat upp än.

Tre saker att ta med sig

Om du sätter upp din första flotta, börja här. description-fältet avgör allt, eftersom det är vad Claude läser när den väljer en arbetare, så skriv den som en routningsregel snarare än en jobbtitel. Designa överlämningen som en fil innan du designar agenten, eftersom ingen subagent någonsin kommer att se en annans kontext. Och sätt varje agent på den billigaste modellen som kan producera ett korrekt svar, och flytta upp den bara när du fångar den ha fel.

Utforska hela biblioteket för specifikationerna bakom den här pipelinen.