Claude Code-subagenter: Det vi lærte av å kjøre 18 i produksjon

Claude Code-subagenter: Det vi lærte av å kjøre 18 i produksjon

Atten Claude Code-subagenter driver hvert eneste innlegg på dette nettstedet, dette inkludert. Seks kjører på Opus, elleve på Sonnet, én på Haiku. researcher-agenten alene har samlet opp 74 minnefiler siden vi startet. Ingen av dem snakker med hverandre. Det er det som overrasket oss mest: en subagent ser aldri samtalen din, og den ser heller aldri en annen subagents samtale. Så hele pipelinen er i stedet bygget rundt filer på disk. Her er flåten, modellfordelingen, minneoppsettet og tingene som gikk galt underveis.

Kort oppsummert:

• En subagent kjører i sitt eget kontekstvindu, med sin egen systemprompt, egne verktøy og egne tillatelser.
• Vi kjører 18 subagenter: 6 på Opus, 11 på Sonnet, 1 på Haiku.
• Agentene overleverer arbeid gjennom filer på disk, aldri gjennom delt kontekst.
• Fra og med v2.1.198 er /agents-opprettelsesveiviseren borte. Skriv filen selv.

Hva er en Claude Code-subagent?

En Claude Code-subagent er en spesialisert assistent som kjører i sitt eget kontekstvindu, med en egen systemprompt, spesifikk verktøystilgang og uavhengige tillatelser. Den utfører en sideoppgave uten å oversvømme hovedsamtalen din, og returnerer deretter bare oppsummeringen sin. Definisjonene ligger som Markdown-filer med YAML-frontmatter i .claude/agents/, dokumentert i Anthropics subagent-referanse.

Claude delegerer til én automatisk. Den leser description-feltet til hver eneste subagent den kan se, og når en oppgave matcher, overlater den arbeidet uten å spørre deg først. Fra og med v2.1.198 kjører disse subagentene i bakgrunnen som standard, så delegeringen skjer ofte mens du fortsatt skriver. Du kan også kalle på én ved navn når du vil ha en bestemt arbeider på en bestemt jobb.

Tre innebygde følger med Claude Code: Explore for skrivebeskyttet kodebase-søk, Plan for planleggingsarbeid, og general-purpose for alt annet.

Én navnedetalj som får både eldre guider og eldre konfigurasjonsfiler til å snuble: verktøyet som spawner en subagent, heter Agent, ikke Task. Det ble omdøpt i v2.1.63, og dokumentasjonen bekrefter at eksisterende Task(...)-referanser fortsatt fungerer som aliaser. Vi bruker Agent gjennom hele dette innlegget.

Resten av dette er ikke en referanse. Anthropics dokumentasjon gjør allerede den jobben bedre enn vi kunne, på rundt 8000 ord med versjonsannotasjoner helt ned til v2.1.212. Det som følger, er hvordan atten av disse ser ut når de kjører hver dag.

Vår 18-agentflåte: Slik ser et reelt oppsett ut på disk

Vår .claude/agents/-mappe inneholder 18 subagent-definisjonsfiler, hver en Markdown-fil med YAML-frontmatter. Sammen kjører de hele innholdspipelinen for dette nettstedet: research, brief-skriving, tekstforfatting, validering, oversettelse til ni språk, bildegenerering og publisering. Seks kjører på Opus, elleve på Sonnet, én på Haiku.

Hver eneste subagent-guide på førstesiden av Google demonstrerer med det samme code-reviewer-eksempelet, kopiert rett ut av dokumentasjonen. Her er hvordan atten av dem ser ut når de faktisk leverer arbeid.

.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 grupperer seg i fire jobber. Innholdsproduksjon kjører researcher inn i brief-creator inn i content-writer inn i validator. Distribusjon dekker translation-coordinator, language-translator, image-handler, payload-publisher og sanity-publisher. Vedlikehold er content-refresher, rank-checker, rescue-diagnoser, rescue-prioritizer, seo-auditor, sitemap-checker og abc-link-checker. Koordinering er pipeline-manager og content-gap-finder.

To av disse filene, kopiert ordrett fra disk, bærer hele 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

Samme mekanisme, omtrent ti ganger kostnaden per token. Den ene er en Opus-agent med nettilgang og vedvarende minne, som avgjør hva et innlegg skal argumentere for. Den andre er en Haiku-agent som henter et sitemap og skriver en JSON-fil. Ingenting i subagent-formatet tvinger deg til å betale Opus-priser for den andre jobben, og de fleste flåtene vi har sett, gjør akkurat det som standard.

skills:-feltet på researcher forhåndslaster to skill-definisjoner inn i denne subagentens systemprompt ved spawning, og det er slik den kjenner SEO-konvensjonene våre uten å bli fortalt det hver gang. Hvis du ikke har skrevet en selv ennå, har vi dekket hvordan du skriver en Claude-skill separat, og dette innlegget gjentar det ikke.

Hvis du vil ha en katalog med definisjoner du kan bla gjennom og kopiere fra, er fellesskapssamlingen awesome-claude-code-subagents den folk faktisk søker etter. Les den for formene, ikke for aktualiteten: enkelte oppføringer er eldre enn Agent-omdøpingen.

Hvordan oppretter du en subagent? («/agents»-veiviseren er borte)

Du oppretter en Claude Code-subagent ved å skrive en Markdown-fil inn i .claude/agents/ selv, eller ved å be Claude skrive den for deg. Fra og med v2.1.198 åpner ikke lenger /agents-kommandoen den interaktive opprettelsesveiviseren. Å kjøre den nå skriver bare ut en påminnelse som peker deg mot mappen.

1. Opprett filen. .claude/agents/{name}.md for en prosjekt-subagent som sendes med i versjonskontroll, eller ~/.claude/agents/{name}.md for én som følger deg på tvers av prosjekter.
2. Skriv name og description. description avgjør mer enn noe annet i filen, fordi det er dette Claude matcher mot når den velger om den skal delegere. Skriv den som en rutingregel, ikke en stillingstittel.
3. Sett tools og model. tools er en tillatelsesliste; utelater du den, arver subagenten verktøyene til hovedsamtalen. model overstyrer sesjonsmodellen din.
4. Skriv systemprompten som Markdown-hoveddelen under frontmatteren. Subagenter mottar bare denne prompten pluss grunnleggende miljødetaljer, ikke hele Claude Codes systemprompt.
5. Kall på den. Automatisk, ved å la description matche, eller eksplisitt ved å be om den ved navn.

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

Flere guider som fortsatt rangerer godt, forteller leserne å kjøre /agents for å åpne administrasjonsgrensesnittet. Den instruksjonen er død. Én ting til dokumentasjonen er eksplisitt på: filovervåkeren dekker bare mapper som eksisterte da sesjonen startet, så den første agentfilen i en helt ny agents/-mappe trenger en omstart av Claude Code før den lastes inn.

Subagent vs. skill vs. agent-team vs. fork: Hvilken trenger du egentlig?

Velg en subagent når en sideoppgave ville oversvømme hovedsamtalen din, og du bare trenger oppsummeringen tilbake. Velg en skill når du vil lære Claude en prosedyre den kjører inne i konteksten du allerede har. Velg et agent-team når arbeiderne må koordinere med hverandre. Velg en fork når sideoppgaven trenger samtalehistorikken din.

Subagenter rapporterer til deg og aldri til hverandre. Agent-team sender meldinger direkte til hverandre. Den ene forskjellen avgjør hvilken primitiv du trenger.

Standarden vår er subagenten, og vi har aldri trengt et team. Koordineringen i pipelinen vår er sekvensiell snarere enn samtalebasert, så en delt oppgaveliste ville ikke gitt noe og bare kostet tokens. Team er dessuten fortsatt eksperimentelt og av som standard, noe som er en hard stopper for alt vi kjører ubetjent. Skills ligger på et helt annet lag: de er instruksjoner som lastes inn i hvilken som helst kontekst som allerede kjører, inkludert en subagents, og det er derfor researcher erklærer to av dem i stedet for å delegere til dem.

Modellvalg: Hvilke agenter hører hjemme på Haiku, Sonnet og Opus

Sett model i frontmatteren til en subagent til haiku, sonnet, opus, eller en spesifikk modell-ID, og den subagenten overstyrer sesjonsmodellen din. Vår reelle fordeling over 18 agenter er seks på Opus, elleve på Sonnet, én på Haiku, tildelt etter hvor mye skjønn agentens resultat faktisk krever.

Tre regler vi ville gitt til hvem som helst som deler en flåte inn i nivåer. Sett en agent på Haiku når resultatet er deterministisk og inndataen er liten: henting, parsing, telling, omformatering. Sett en agent på Sonnet når oppgaven er lang og godt spesifisert, men noen allerede har bestemt hvordan et «korrekt» resultat ser ut, noe som dekker det meste av utførelsesarbeidet, inkludert alle de ni oversettelsesarbeiderne. Reserver Opus for agenter hvis resultat ingenting nedstrøms vil stille spørsmål ved.

Den siste regelen er grunnen til at validator sitter på Opus, selv om den produserer en kort rapport. Ingenting sjekker kontrolløren.

Én versjonsmerknad som endrer regnestykket: siden v2.1.198 kjører den innebygde Explore-subagenten ikke lenger alltid på Haiku, den arver sesjonsmodellen. En bruker- eller prosjektnivå-subagent kalt Explore overstyrer den innebygde og beholder sitt eget model-felt, så definer én med model: haiku hvis du vil holde utforsking på en billig modell.

Filkontrakter: Hvordan agentene våre overleverer arbeid uten å dele kontekst

En subagent ser ikke samtalehistorikken din, og den ser ikke en annen subagents heller. Overlevering i minnet mellom agenter er derfor strukturelt umulig. Løsningen er å gjøre hver overlevering til et artefakt på disk, slik at neste agent leser en fil i stedet for å arve en kontekst den aldri 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, hver skrevet av en annen agent, hver lest av den neste, alle lesbare for et menneske og sporet i git. Pipelinen overlever kontekstgrenser fordi ingen agent noensinne trenger en annen agents kontekst. Den trenger bare den forrige agentens fil.

Den tydeligste gevinsten er oversettelse. translation-coordinator leser en.md, og spawner deretter én language-translator-subagent per språk, ni eller ti av dem samtidig. I vårt repo avhenger samtidigheten av at alle spawn-kallene sendes i én og samme melding: det er observert atferd i vårt oppsett snarere enn noe dokumentasjonen fastslår, men det har vært konsekvent nok til at koordinatoren er skrevet for å gjøre det med vilje. Hver oversetter skriver sin egen {lang}.md, og ingen av dem kan se hverandres arbeid, noe som er greit, fordi kontrakten er filen, og filen er allerede komplett.

Dette er også der subagenter slutter og noe annet begynner. Subagenter jobber inne i én enkelt sesjon. Hvis du vil ha genuint uavhengige arbeidsområder med sine egne historikker, kjører du flere Claude Code-sesjoner i stedet, eller griper til isolation: worktree for å gi én subagent sin egen kopi av repositoriet.

Hvordan husker subagenter ting mellom sesjoner?

Bare hvis du setter memory-feltet, som tar tre omfang: user skriver til ~/.claude/agent-memory/<name>/, project skriver til .claude/agent-memory/<name>/, og local skriver til .claude/agent-memory-local/<name>/. Uten det starter hvert kall blankt. Tolv av våre atten agenter erklærer memory: project.

Etter rundt førti innlegg er disse mappene betydelige. researcher har 74 minnefiler, validator 66, brief-creator 65. De er ikke logger. De er akkumulerte avgjørelser: hvilke H1-mønstre som underpresterte, hvilke kundepåstander vi ikke kan fremsette, hvilke SERP-former som belønner en tabell fremfor prosa.

Her er begrensningen som former alt sammen. En minneaktivert subagent får bare de første 200 linjene eller 25 KB av MEMORY.md injisert i systemprompten sin, avhengig av hva som kommer først. Denne ene grensen er grunnen til at hver eneste av agentene våre holder en indeks i stedet for 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

Én linje per oppføring, detaljene skjøvet inn i den lenkede emnefilen, som agenten leser på forespørsel med sitt Read-verktøy. MEMORY.md forblir en indeks som passer innenfor injeksjonsbudsjettet, mens korpuset bak den vokser uten grense.

Vi bruker project fremfor user for nesten alt, fordi prosjektminne bor i repoet og reiser med gjennom versjonskontroll. Når en lagkamerat henter (pull), henter de agentens akkumulerte vurderinger sammen med koden. local finnes for tilfellene der du vil ha notatene, men ikke committen.

Hva som gikk i stykker: Feilmoduser, duplikatnavn og et gammelt alias i vårt eget repo

Fire feilmoduser står for nesten alt vi har møtt på. En subagent som nekter å starte, en subagent som stille ikke er den du redigerte, en subagent Claude ikke finner i det hele tatt, og et hardt sesjonstak på hvor mange du kan spawne. Alle fire har korte, entydige løsninger.

Duplikatnavn-tilfellet er slemmere enn det høres ut. Du redigerer en fil, atferden endrer seg ikke, og det finnes ingen feilmelding noe sted, fordi en annen fil med samme name vant leserekkefølgen.

Hooks hjalp mer enn vi forventet for feilene som ikke er feil i det hele tatt, bare steg et menneske glemmer. Vår er bevisst dum:

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

Nå den ærlige delen. Mens vi skrev dette innlegget, grep-et vi vår egen flåte og fant dette som fortsatt lå i translation-coordinator.md:

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

Task, ikke Agent. Det feltet har vært utdatert siden v2.1.63, og det har aldri sviktet én eneste gang, fordi Anthropic beholdt aliaset. Vi har ikke ryddet det opp ennå. Hvis dine egne agentfiler fortsatt sier Task, er de ikke ødelagt, de er bare gamle, og aliaset gjør stille arbeid for mange repoer akkurat nå.

Én korreksjon i motsatt retning: guider skrevet før v2.1.172 forteller leserne at en subagent ikke kan spawne subagenter. Det kan den, og har kunnet siden den utgivelsen. Dybden er fast satt til fem nivåer under hovedsamtalen og er ikke konfigurerbar, så en subagent på dybde fem mottar rett og slett ikke Agent-verktøyet.

Hva subagenter koster, og når du ikke bør bruke én

Hver subagent-spawning oppretter et ferskt kontekstvindu, så delegering er aldri gratis. Anthropics ingeniørteam rapporterer at agenter bruker omtrent 4x flere tokens enn chat-interaksjoner, og at multiagentsystemer bruker omtrent 15x flere, og at tokenbruk alene forklarer 80 % av ytelsesvariasjonen de målte.

Vi har ingen egne tokenmålinger å legge til, så behandle enhver spesifikk multiplikator du leser om dette emnet, inkludert 4x-til-7x-tallene som flyter rundt i andre blogginnlegg, som den forfatterens tall snarere enn en benchmark. Anthropics gjennomgang av multiagent-forskningssystemet er den ene kilden her med ekte data bak seg, og den samme studien fant at en Opus-ledeagent med Sonnet-subagenter slo en enkelt Opus-agent med 90,2 % i deres interne evaluering. Det resultatet, ikke tokentellingen, er argumentet for nivådeling.

Hopp over subagenten når resultatet uansett hører hjemme i hovedsamtalen din, fordi du bare kommer til å lime det inn igjen og betale to ganger. Hopp over den for små endringer der delegeringens rundtur koster mer enn å gjøre arbeidet selv. Og hopp over den når oppgaven genuint trenger samtalehistorikken din: bruk en fork i stedet, som arver hele samtalen og gjenbruker forelderens promptcache, noe som gjør den billigere enn en fersk subagent for sidearbeid som krever mye kontekst. Anthropics egen kostnadsveiledning og deres rammeverk for når du bør bruke hva lander begge på samme sted.

Taket på 200 per sesjon er verdt å kjenne til før du designer en fordeling av mange subagenter. Det er en reell grense mot delegering som løper løpsk, og å heve den er en bevisst handling snarere enn en standard.

Om forfatteren

Mert Batur bygger hos Techsy, der teamet leverer AI-agenter, automasjonssystemer og voice/SDR-pipelines for B2B-kunder. Han skriver om LLM-verktøykjeden og Claude Skills som Techsy-teamet faktisk bruker i produksjon. Ta kontakt på LinkedIn.

Ofte stilte spørsmål

Hva er Claude Code-subagenter?

Claude Code-subagenter er spesialiserte assistenter som hver kjører i sitt eget kontekstvindu, med en egen systemprompt, begrenset verktøystilgang og uavhengige tillatelser. Du definerer én som en Markdown-fil med YAML-frontmatter i .claude/agents/. Subagenten utfører en sideoppgave og returnerer bare oppsummeringen sin til hovedsamtalen din.

Bruker Claude Code subagenter automatisk?

Ja. Claude leser description-feltet til hver eneste subagent som er tilgjengelig for den, og delegerer når en oppgave matcher, uten å spørre deg først. Fra og med v2.1.198 kjører subagenter i bakgrunnen som standard, så det delegerte arbeidet skjer ofte mens du fortsatt skriver i hovedsamtalen.

Hvor ligger subagent-filene?

Prosjekt-subagenter ligger i .claude/agents/, og bruker-subagenter i ~/.claude/agents/. Begge stedene skannes rekursivt, så undermapper er greit. Identitet kommer bare fra name-frontmatterfeltet, aldri fra stien. Administrerte subagenter distribuert av en administrator går foran prosjekt- og brukerdefinisjoner som deler samme navn.

Hvordan kaller jeg eksplisitt på en subagent?

Be om den ved navn i prompten din, for eksempel «bruk validator-subagenten på dette utkastet». Eksplisitt kall omgår beskrivelsesmatchingen som driver automatisk delegering, noe som hjelper når to av subagentene dine har overlappende beskrivelser og Claude stadig griper etter feil én.

Kan en subagent spawne sine egne subagenter?

Ja, siden Claude Code v2.1.172. Guider skrevet før den utgivelsen fastslår at nøsting er umulig, og de er utdaterte. Dybde telles i nivåer under hovedsamtalen og er fast satt til fem: en subagent på dybde fem mottar ikke Agent-verktøyet. Grensen er ikke konfigurerbar.

Husker subagenter noe mellom sesjoner?

Bare hvis du setter memory-feltet. Det godtar user for ~/.claude/agent-memory/<name>/, project for .claude/agent-memory/<name>/, eller local for .claude/agent-memory-local/<name>/. Uten det starter hvert kall blankt. Tolv av våre atten agenter bruker memory: project, slik at notatene deres reiser med i versjonskontroll.

Kan en subagent bruke en annen modell enn sesjonen min?

Ja. Sett model i frontmatteren til haiku, sonnet, opus, eller en spesifikk modell-ID, og den overstyrer sesjonsmodellen din for den subagenten. Flåten vår deler seg i seks på Opus, elleve på Sonnet og én på Haiku, tildelt etter hvor mye skjønn hver agents resultat krever.

Hvorfor dukker ikke den nye subagenten min opp?

Tre vanlige årsaker. agents-mappen eksisterte ikke da sesjonen startet, så overvåkeren fanget den aldri opp: start Claude Code på nytt. Eller to filer deler samme name, og bare én lastes inn. Eller ingenting i tools-listen din lar seg løse, noe som siden v2.1.208 nekter å starte med en navngitt feilmelding.

Er Task fortsatt et gyldig verktøynavn?

Ja, som et alias. Task-verktøyet ble omdøpt til Agent i v2.1.63, og eksisterende Task(...)-referanser fungerer fortsatt i innstillinger og agentdefinisjoner. Skriv Agent i nye filer. Vår egen translation-coordinator.md erklærer fortsatt Task, noe vi oppdaget mens vi skrev dette innlegget, og som vi ikke har ryddet opp i.

Tre ting å ta med seg

Hvis du setter opp din første flåte, start her. description-feltet avgjør alt, fordi det er dette Claude leser når den velger en arbeider, så skriv det som en rutingregel snarere enn en stillingstittel. Design overleveringen som en fil før du designer agenten, siden ingen subagent noensinne vil se en annens kontekst. Og sett hver agent på den billigste modellen som kan produsere et korrekt svar, og flytt den bare opp når du tar den i å ta feil.

Utforsk hele biblioteket for spesifikasjonene bak denne pipelinen.