Claude Code subagenter: en praktisk guide (2026)

En subagent är en andra Claude, lanserad av din huvudsakliga Claude Code-session, som kör en uppgift i sitt eget kontextfönster och lämnar tillbaka ett resultat. Den delar inte din konversationshistorik. Den ser inte filerna du redan läst eller besluten du redan fattat. Den får en prompt, gör arbetet, och returnerar.

Den isoleringen är hela funktionen. Parallelliteten, specialiseringen, de anpassade verktygsbegränsningarna, allt av det är nedströms från ett faktum: en subagent bränner sitt eget kontextfönster och bara slutsvaret kommer tillbaka till ditt.

Vi kör dussintals subagenter om dagen när vi bygger SkillProof, mestadels för forskningsutspridning och oberoende fixar över katalogens datafiler. Delar av vad vi lärt oss är genuint användbart. Delar av det lärde vi oss genom att se en agent hävda seger över arbete den aldrig gjorde. Båda typerna finns i den här guiden.

Vad en subagent faktiskt är

I Claude Code är huvudsessionen en loop: läs, tänk, agera, observera, upprepa, med varje steg tillagt till en växande konversation. En subagent är en separat instans av samma loop, startad mitt i sessionen, med sin egen historik som börjar tom förutom prompten du ger den.

När subagenten är klar reser inget av dess mellanliggande arbete tillbaka. Inte filerna den läste, inte kommandona den körde, inte återvändsgränderna den utforskade. Bara texten den väljer att returnera landar i din huvudkontext. Om den läste 40 filer för att svara på din fråga betalar din huvudsession för ingen av dessa 40 läsningar. Den betalar för en sammanfattning.

Det är varför subagenter beskrivs som ett sätt att bevara kontext: inte för att arbetet är gratis (det kostar samma tokens någonstans), utan för att kostnaden är karantänsatt i ett fönster som slängs bort, inte ett du fortsätter dra genom resten av sessionen.

Avvägningen följer direkt. En subagent som inte vet vad du redan provat kan upprepa dina egna återvändsgränder, och den kan inte ställa en förtydligande fråga mitt i uppgiften på det sätt huvudloopen kan, den antingen har tillräckligt i prompten för att fortsätta eller så gissar den. Delegering köper isolering och kostar delat minne. Varje bra subagentprompt är skriven av någon som internaliserat den avvägningen.

Varför kontextisolering är poängen

Föreställ dig en huvudsession två timmar in i en refaktorering: fyrtio filer lästa, ett dussin verktygsanrop, ett designbeslut omprövat två gånger. Den historiken gör riktigt arbete, det är vad som gör nästa redigering sammanhängande, men det är också femtiotusen tokens av barlast.

Nu behöver du veta hur ett orelaterat delsystem hanterar återförsök. Läs de filerna i huvudloopen och var och en blir permanent bagage, åkande i kontexten för resten av sessionen oavsett om du använder den igen eller inte, tills det är en del av varför modellen börjar tappa greppet om den faktiska refaktoreringen. En subagent låter dig ställa frågan, få svaret, och gå ifrån läsandet. De fyrtio filerna den läste går aldrig in i ditt fönster. Du får ett stycke tillbaka.

Det är mekanismen bakom varje legitim subagentvinst i den här guiden: forskning, parallella fixar, brusig utforskning. Alla av dem är egentligen samma drag, gör det dyra läsandet någonstans engångsbart, håll huvudtråden ren.

När subagenter slår att jobba i huvudloopen

Forskning över många filer. "Hur flödar autentisering genom den här kodbasen" rör routes, mellanprogramvara, sessionslagring och tre konfigurationsfiler. Att svara på det i huvudloopen betyder att allt av det landar i din kontext permanent. En subagent läser samma filer, returnerar en syntes, och råmaterialet försvinner med den.

Parallella oberoende uppgifter. Fem komponenter behöver alla samma prop omdöpt. Ingen är beroende av den andra. Fem subagenter som körs samtidigt slutför på ungefär den tid en tar, utan delat tillstånd att koordinera mellan ändringarna.

Brusig utforskning. Att greppa efter ett mönster över ett stort repo, prova tre söktekniker innan en träffar, läsa filer som visar sig irrelevanta. Det här är exakt det arbete du vill karantänsätta. En subagent kan flaxa ett tag och bara den användbara delen kommer tillbaka.

Isolera en specialiserad persona. En kodgranskningssubagent som bara någonsin granskar, med en smalare verktygsuppsättning och en prompt tunad för skepsis, beter sig mer konsekvent än att be din huvudagent kontextväxla till "var nu kritisk mot ditt eget arbete" mitt i sessionen.

När subagenter är sämre

Tighta iterativa loopar. Att felsöka ett misslyckat test genom att ändra en rad, köra om, läsa det nya felet, ändra en annan rad, behöver hela historiken av vad du redan provat. Att lämna det till en ny subagent varje iteration betyder att förklara om hela utredningen varje gång, långsammare och sämre än att stanna i huvudloopen. Det här är territoriet våra systematisk felsökning-anteckningar täcker: felsökning vill ha kontinuitet, inte delegering.

Uppgifter som behöver hela konversationen. Om användaren spenderade tio meddelanden på att förfina exakt vad "städa upp det här API:et" betyder, kommer en subagent som bara ser slutinstruktionen städa upp det efter sin egen gissning av "städa", inte den ni förhandlade fram. Allt där kraven bor i konversationen snarare än en prompt du kan återge är en dålig match.

Enkla enfilsredigeringar. Att delegera "byt namn på den här variabeln i den här filen" till en subagent lägger till en rundtur, en ny kontextladdning, och ett resultat du fortfarande måste läsa och lita på, för arbete som skulle tagit femton sekunder direkt. Att spinna upp en isolerad arbetare lönar sig bara när arbetet den skyddar dig från är genuint stort.

Mönstret genom alla tre: subagenter är sämre exakt när värdet av delad kontext överväger kostnaden att bära den. Isolering slutar vara en funktion i samma stund kontinuitet är vad uppgiften behövde.

Anpassade agentdefinitioner

Claude Code laddar anpassade subagenter från markdown-filer under .claude/agents/ (projektnivå, delad genom git) eller ~/.claude/agents/ (personlig, alla projekt). Varje fil är en agent: frontmatter plus en systemprompt, samma form som en skill men beskriver en persona i stället för en procedur.

Här är ett fullständigt, kommenterat exempel, en kodgranskare avgränsad till läsonly-granskningsarbete:

---
name: code-reviewer
description: Reviews a diff or pull request for correctness bugs,
  security issues, and missed edge cases. Use after a change is
  written and before it's committed, not while still drafting.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior engineer doing a pre-commit review. You did not
write this code and you have no attachment to it.

When given a diff or a set of changed files:

1. Read every changed file in full, not just the diff hunks.
   Bugs hide in the context around a change as often as in the
   change itself.
2. Check for: unhandled errors, off-by-one boundaries, null or
   undefined paths the type system doesn't catch, and any
   secret or credential that shouldn't be committed.
3. Do not comment on style or formatting unless it hides a bug.
   A linter's job is not your job.
4. For each finding, cite the file and line, and say what
   breaks and how you'd confirm it. If you're not sure something
   is a bug, say so explicitly instead of stating it as fact.
5. If you find nothing, say that plainly. Do not invent minor
   issues to look thorough.

Never run commands that modify files. You are reviewing, not fixing.

Några saker spelar roll här. name är hur du anropar den (Use the code-reviewer agent to check this diff) eller hur Claude Code anropar den automatiskt på en matchande uppgift. description-fältet bär samma vikt det gör i en skill: specifika triggervillkor slår en vag sammanfattning.

tools är en genuin säkerhetsgräns, inte ett förslag. Att lista bara Read, Grep, Glob, Bash betyder att den här agenten fysiskt inte kan anropa Edit eller Write, även om dess eget resonemang bestämde att en fix var uppenbar. Det är avsiktligt: en granskningsagent som också kan patcha koden den granskar är en du inte kan lita på att bara granska. model låter dig routa en mekanisk, väl specificerad agent till en billigare modell än din huvudsession, eftersom uppgiften inte behöver din primära modells fulla vikt.

Kroppen är samma hantverk som en skill: negativa begränsningar ("kommentera inte stil", "hitta inte på mindre problem") gör mer nytta än positiva, för de är vad som stoppar en granskare från att fylla ut sin output för att se grundlig ut.

Parallella mönster som faktiskt fungerar

Fan-out-läsningar. Lansera flera subagenter samtidigt, var och en tilldelad en olika del av samma fråga: en läser autentiseringsmodulen, en datalagret, en testsviten. Var och en returnerar en kort syntes. Du får tre svar på tiden en sekventiell körning skulle ta, och råfilinnehållet rör aldrig din huvudkontext.

N oberoende fixar. En batch komponenter behöver samma mekaniska ändring, och ingen importerar från varandra. Lansera en subagent per komponent, var och en med en självständig prompt: den exakta ändringen, den exakta filen, den exakta acceptanskontrollen. Det här är det renaste parallella fallet, ingen subagent behöver veta vad en annan gjorde.

Båda mönstren delar ett krav som är lätt att missa och dyrt när man gör det: varje prompt måste vara självständig. Den har inte din konversation. Om uppgiften beror på ett beslut fattat tre meddelanden tidigare måste det beslutet återges i prompten, annars kommer subagenten säkert göra fel sak.

Fellägen vi faktiskt stött på

Det här är delen de flesta guider hoppar över, skriven av någon som kört en subagent två gånger och det fungerade. Vi kör dem dagligen, och här är vad som går sönder i praktiken.

Agenter som rapporterar "klart" utan att göra arbetet. En subagent kommer tillbaka med en ren, säker sammanfattning: "Uppdaterade de tre filerna, testerna passerar, redo att committa." Du kollar, och en fil är orörd. Det här är inte modellen som är oärlig i någon medveten mening, det är returstsammanfattningen som glider från vad som faktiskt hände, särskilt på längre uppgifter där agentens egen redogörelse för sitt arbete blir komprimerad. Fixen är tråkig och icke förhandlingsbar: verifiera efter artefakt, inte efter rapport. Läs diffen själv. Kör testet själv. En subagents sammanfattning är ett påstående, inte ett kvitto.

Agenter som väntar på fantomnotifieringar. Vi har haft subagenter pausa mitt i en uppgift, väntande på en callback eller en signal från en annan process som aldrig skulle komma, för att koordineringsmekanismen bara fanns i promptens fantasi, inte i något faktiskt kopplat. Fixen är att aldrig designa en subagentprompt runt en händelse du inte verifierat utlöses. Om en subagents nästa steg beror på en annan agents output, ge den outputen direkt när du lanserar den, be den inte upptäcka en slutsignal du inte byggt.

Båda misslyckandena spårar tillbaka till samma disciplin: en prompt som inte lutar sig mot delad kontext eller en antagen notifiering är en en agent faktiskt kan slutföra korrekt, och ett utfall du kontrollerar genom att läsa filen, inte genom att läsa agentens redogörelse för filen, är det enda sättet att veta att den gjorde det. Inget av det här är ett argument mot subagenter. Det är ett argument mot att lita på en textsammanfattning på samma sätt du skulle lita på en diff. Vi kör dem konstant. Vi bara mergar inget på deras ord ensamt.

Skills fungerar inuti subagenter också

En subagent är fortfarande en Claude-instans, så den laddar skills på samma sätt din huvudsession gör: matchande sin uppgift mot installerade skill-beskrivningar och dragande in kroppen vid trigger. En kodgranskningssubagent med vår kodgranskningschecklista-skill installerad får samma strukturerade genomgång den skulle i huvudloopen, avgränsad till vilken diff du än gav den.

Det här komponerar rent. Subagenten hanterar var arbetet sker, skillen hanterar hur det görs. Ingen behöver veta om den andra; de staplas automatiskt så länge båda är installerade där subagenten kan se dem, projektskills i .claude/skills/, personliga skills i ~/.claude/skills/. Vår sida bästa kodningsskills rankar de värda att installera innan du kopplar upp en gransknings- eller forskningsagent.

Subagenter vs hooks vs skills

Tre olika mekanismer, tre olika jobb, och de blandas ihop konstant:

	Vad den gör	Utlöser på	Körs var
Skill	Lär Claude en procedur eller stil	Claude matchar din begäran mot en beskrivning	Inuti aktuell kontext
Hook	Kör ett fast skalkommando automatiskt	En livscykelhändelse (innan ett verktygsanrop, efter ett svar, sessionsstart)	Utanför modellen, deterministisk
Subagent	Delegerar en uppgift till en isolerad Claude-instans	Ett explicit anrop, av dig eller huvudagenten	Ett separat kontextfönster

En skill ändrar hur Claude angriper något den redan ska göra. En hook framtvingar något varje gång, ovillkorligt, utan att be modellen komma ihåg: kör tester efter varje redigering, blockera en commit om hemligheter upptäcks. En subagent ändrar var arbetet sker, flyttar det till ett engångsbart fönster i stället för ditt huvudsakliga. Vi täcker hooks djupgående, inklusive samma typ av ärrvävnad som ovan, i vår Claude Code hooks-guide.

De staplas. En teamuppsättning kan använda en hook för att linta efter varje skrivning, en skill för att lära ut husets kodstil, och en subagent för att köra den fulla granskningsomgången innan merge, tre lager, inget redundant. Om du fortfarande sätter ihop resten av din uppsättning går vår 2026-installationsguide igenom var varje del hör hemma, och vår tokenkostnadsguide täcker vad alla tre kostar i vila.

Vanliga frågor

Delar subagenter min huvudsessions kontext?

Nej, och det är hela poängen. En subagent startar med en tom historik förutom prompten du ger den. Inget från din huvudkonversation förs över automatiskt, och inget subagenten läser eller gör förs tillbaka förutom slutet den returnerar. Om den behöver bakgrund från din konversation, lägg den bakgrunden i prompten.

Kan subagenter köras parallellt?

Ja. Att lansera flera samtidigt är standardmönstret för fan-out-forskning och för oberoende, icke-överlappande fixar. Var och en får sitt eget kontextfönster, så de stör inte varandra, men de kan heller inte koordinera mitt i uppgiften om du inte explicit matat en agents output in i en annans prompt.

Hur vet jag om en subagent faktiskt gjorde vad den påstod?

Kolla artefakten, inte sammanfattningen. Läs diffen, kör testet, öppna filen. Vi har haft subagenter rapportera ren framgång på arbete som var delvis ogjort, inte av oärlighet utan för att en sammanfattning är en rekonstruktion, och rekonstruktioner glider. Behandla varje subagentrapport som ett påstående att verifiera.

Var bor anpassade agentdefinitioner?

.claude/agents/*.md för projektnivå-agenter som följer med repot genom git, och ~/.claude/agents/*.md för personliga sådana tillgängliga i alla projekt. Varje fil behöver name och description i sin frontmatter som minimum; tools och model är valfria men värda att sätta medvetet snarare än att lämna på sina standardvärden.

Ska jag begränsa vilka verktyg en subagent kan använda?

Ja, närhelst agenten har ett smalt jobb. En granskningsagent som inte kan anropa Edit kan inte oavsiktligt patcha det den ska kritisera. En läsonly-forskningsagent som inte kan anropa Bash kan inte köra något destruktivt av misstag medan den snokar runt. tools-fältet i en agents frontmatter är mekanismen, och att sätta det är billigare än att felsöka vad en överdrivet mäktig agent gjorde med sin återstående tid.