Claude Code subagenti: praktický průvodce (2026)

Subagent je druhý Claude, spuštěný vaší hlavní session Claude Code, který provede úkol ve vlastním kontextovém okně a vrátí výsledek. Nesdílí historii vaší konverzace. Nevidí soubory, které jste už přečetli, ani rozhodnutí, která jste už udělali. Dostane prompt, udělá práci a vrátí se.

Tahle izolace je celá funkce. Paralelismus, specializace, vlastní omezení nástrojů – to všechno vyplývá z jednoho faktu: subagent spaluje vlastní kontextové okno a do vašeho se vrátí jen finální odpověď.

Při stavbě SkillProof spouštíme desítky subagentů denně, hlavně na výzkumné rozvětvení a nezávislé opravy napříč datovými soubory katalogu. Něco z toho, co jsme se naučili, je opravdu užitečné. Něco jsme se naučili tím, že jsme sledovali agenta, jak si připisuje vítězství za práci, kterou nikdy neudělal. Oba druhy jsou v tomto průvodci.

Co subagent vlastně je

V Claude Code je hlavní session smyčka: čti, mysli, jednej, pozoruj, opakuj, přičemž se každý krok přidává do jedné rostoucí konverzace. Subagent je samostatná instance téže smyčky, spuštěná uprostřed session, s vlastní historií, která začíná prázdná až na prompt, který mu dáte.

Když subagent skončí, žádná z jeho mezikroků se nevrací zpátky. Ne soubory, které přečetl, ne příkazy, které spustil, ne slepé uličky, které prozkoumal. Do vašeho hlavního kontextu dopadne jen text, který se rozhodne vrátit. Pokud přečetl 40 souborů, aby odpověděl na vaši otázku, vaše hlavní session neplatí za žádné z těch 40 čtení. Platí za jedno shrnutí.

Proto se subagenti popisují jako způsob, jak zachovat kontext: ne proto, že by práce byla zadarmo (stojí stejné tokeny někde jinde), ale protože je náklad zakarantovaný v okně, které se zahodí, ne v tom, které dál táhnete zbytkem session.

Kompromis z toho vyplývá přímo. Subagent, který neví, co jste už zkusili, může zopakovat vaše vlastní slepé uličky, a uprostřed úkolu se nemůže zeptat na doplňující otázku tak, jak to umí hlavní smyčka – buď má v promptu dost na to, aby pokračoval, nebo hádá. Delegování kupuje izolaci a stojí sdílenou paměť. Každý dobrý prompt pro subagenta píše někdo, kdo si tenhle kompromis vzal k srdci.

Proč je izolace kontextu tím hlavním

Představte si hlavní session dvě hodiny uprostřed refaktoringu: čtyřicet přečtených souborů, tucet volání nástrojů, návrhové rozhodnutí přehodnocené dvakrát. Tahle historie odvádí skutečnou práci, je to to, co dělá další úpravu koherentní, ale je to zároveň padesát tisíc tokenů zátěže.

Teď potřebujete zjistit, jak jeden nesouvisející subsystém řeší opakované pokusy. Přečtěte si ty soubory v hlavní smyčce a každý z nich se stane trvalou přítěží, jezdí v kontextu po zbytek session, ať ho znovu použijete, nebo ne, dokud se nestane součástí toho, proč model začne ztrácet nit skutečného refaktoringu. Subagent vám umožní položit otázku, dostat odpověď a od toho čtení odejít. Čtyřicet souborů, které přečetl, se do vašeho okna nikdy nedostane. Vrátí se vám jeden odstavec.

To je mechanismus za každým legitimním vítězstvím subagenta v tomto průvodci: výzkum, paralelní opravy, hlučné zkoumání. Všechny jsou ve skutečnosti stejný tah – udělejte drahé čtení někde jednorázovém, udržte hlavní vlákno čisté.

Kdy subagenti porazí práci v hlavní smyčce

Výzkum napříč mnoha soubory. „Jak prochází autentizace touhle codebase" se dotýká rout, middlewaru, ukládání session a tří konfiguračních souborů. Zodpovězení v hlavní smyčce znamená, že tohle všechno trvale skončí ve vašem kontextu. Subagent přečte stejné soubory, vrátí syntézu, a surový materiál s ním zmizí.

Paralelní nezávislé úkoly. Pět komponent potřebuje stejné přejmenování propu. Žádná na sobě nezávisí. Pět subagentů běžících naráz skončí ve zhruba stejném čase jako jeden, bez sdíleného stavu, který by bylo třeba koordinovat mezi změnami.

Hlučné zkoumání. Greppování vzoru napříč velkým repozitářem, zkoušení tří vyhledávacích strategií, než jedna zabere, čtení souborů, které se ukážou jako irelevantní. Přesně tohle je práce, kterou chcete zakarantovat. Subagent může chvíli tápat a vrátí se jen užitečná část.

Izolace specializované persony. Subagent pro code review, který jen recenzuje, s užší sadou nástrojů a promptem vyladěným na skepsi, se chová konzistentněji než žádost, aby váš hlavní agent uprostřed session přepnul do „teď buď kritický vůči vlastní práci".

Kdy jsou subagenti horší

Těsné iterativní smyčky. Debugování padajícího testu změnou jednoho řádku, opětovným spuštěním, přečtením nové chyby, změnou dalšího řádku, potřebuje celou historii toho, co jste už zkusili. Předat tohle čerstvému subagentovi při každé iteraci znamená znovu vysvětlovat celé vyšetřování pokaždé, pomaleji a hůř než zůstat v hlavní smyčce. Tohle je území, které pokrývají naše poznámky k systematickému debugování: debugování chce kontinuitu, ne delegování.

Úkoly potřebující celou konverzaci. Pokud uživatel strávil deset zpráv upřesňováním, co přesně znamená „ukliď tohle API", subagent, který vidí jen finální instrukci, ho ukliní podle vlastního odhadu „úklidu", ne toho, na kterém jste se dohodli. Cokoli, kde zadání žije v konverzaci místo v promptu, který dokážete zrekapitulovat, je špatná shoda.

Jednoduché úpravy jednoho souboru. Delegovat „přejmenuj tuhle proměnnou v tomhle souboru" na subagenta přidává zpáteční cestu, čerstvé načtení kontextu a výsledek, který stejně musíte přečíst a ověřit, kvůli práci, která by přímo trvala patnáct vteřin. Spouštění izolovaného workeru se vyplatí, jen když je práce, před kterou vás chrání, skutečně velká.

Vzorec napříč všemi třemi: subagenti jsou horší přesně tehdy, kdy hodnota sdíleného kontextu převáží nad náklady na jeho nesení. Izolace přestává být výhodou ve chvíli, kdy úkol potřeboval kontinuitu.

Vlastní definice agentů

Claude Code načítá vlastní subagenty z markdown souborů pod .claude/agents/ (na úrovni projektu, sdílené přes git) nebo ~/.claude/agents/ (osobní, ve všech projektech). Každý soubor je jeden agent: frontmatter plus systémový prompt, stejný tvar jako u skillu, ale popisuje personu místo postupu.

Tady je plný, okomentovaný příklad – code-reviewer omezený na práci s review jen pro čtení:

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

Pár věcí tady záleží. name je způsob, jak agenta vyvoláte (Use the code-reviewer agent to check this diff) nebo jak ho Claude Code vyvolá automaticky u odpovídajícího úkolu. Pole description má stejnou váhu jako u skillu: konkrétní podmínky spouštění porazí vágní shrnutí.

tools je skutečná bezpečnostní hranice, ne doporučení. Uvedení pouze Read, Grep, Glob, Bash znamená, že tenhle agent fyzicky nemůže zavolat Edit ani Write, i kdyby jeho vlastní uvažování usoudilo, že oprava je zjevná. To je záměr: agent pro review, který zároveň dokáže patchovat kód, který recenzuje, je agent, kterému nemůžete věřit, že se bude držet jen review. model vám umožní nasměrovat mechanického, dobře zadaného agenta na levnější model než vaše hlavní session, protože úkol nepotřebuje plnou váhu vašeho primárního modelu.

Tělo je stejné řemeslo jako u skillu: negativní omezení („nekomentuj styl", „nevymýšlej drobné problémy") odvádí víc práce než pozitivní, protože právě ona brání recenzentovi nafukovat výstup, aby vypadal důkladně.

Paralelní vzory, které skutečně fungují

Rozvětvené čtení. Spusťte několik subagentů najednou, každého s jinou částí stejné otázky: jeden čte modul autentizace, jeden datovou vrstvu, jeden testovací sadu. Každý vrátí krátkou syntézu. Dostanete tři odpovědi v čase, který by zabral jeden sekvenční průchod, a surový obsah souborů se nikdy nedotkne vašeho hlavního kontextu.

N nezávislých oprav. Dávka komponent potřebuje identickou mechanickou změnu a žádná z nich neimportuje z ostatních. Spusťte jednoho subagenta na komponentu, každého se samostatným promptem: přesná změna, přesný soubor, přesná akceptační kontrola. Tohle je nejčistší paralelní případ, žádný subagent nepotřebuje vědět, co udělal jiný.

Oba vzory sdílejí požadavek, který je snadné přeskočit a drahé, když to uděláte: každý prompt musí být soběstačný. Nemá vaši konverzaci. Pokud úkol závisí na rozhodnutí učiněném před třemi zprávami, musí se to rozhodnutí zopakovat v promptu, jinak subagent sebejistě udělá špatnou věc.

Chybové stavy, na které jsme skutečně narazili

Tohle je část, kterou většina průvodců přeskočí, protože je psaná někým, kdo spustil subagenta dvakrát a fungovalo to. My je spouštíme denně, a tohle je to, co se v praxi rozbíjí.

Agenti, kteří hlásí „hotovo", aniž by práci udělali. Subagent se vrátí s čistým, sebejistým shrnutím: „Aktualizoval jsem tři soubory, testy prochází, připraveno k commitu." Zkontrolujete to, a jeden soubor zůstal nedotčený. Není to v žádném záměrném smyslu nepoctivost modelu, je to odklon vráceného shrnutí od toho, co se skutečně stalo, obzvlášť u delších úkolů, kde se agentův vlastní popis vlastní práce zkomprimuje. Oprava je nudná a nesmlouvavá: ověřujte podle artefaktu, ne podle zprávy. Přečtěte si diff sami. Spusťte test sami. Shrnutí subagenta je tvrzení, ne účtenka.

Agenti, kteří čekají na fantomové notifikace. Měli jsme subagenty, kteří se uprostřed úkolu zastavili a čekali na callback nebo signál z jiného procesu, který nikdy nepřišel, protože koordinační mechanismus existoval jen v představivosti promptu, ne v ničem, co bylo skutečně zapojené. Oprava je nikdy nenavrhovat prompt subagenta kolem události, kterou jste neověřili, že se skutečně spouští. Pokud další krok subagenta závisí na výstupu jiného agenta, předejte mu ten výstup přímo, když ho spouštíte, neptejte se ho, aby detekoval signál dokončení, který jste nepostavili.

Obě selhání se vracejí ke stejné disciplíně: prompt, který se neopírá o sdílený kontext nebo předpokládanou notifikaci, je takový, který agent skutečně dokáže dokončit správně, a výsledek, který zkontrolujete přečtením souboru, ne přečtením agentova popisu souboru, je jediný způsob, jak vědět, že se to stalo. Nic z tohohle není argument proti subagentům. Je to argument proti důvěřování textovému shrnutí tak, jak byste důvěřovali diffu. Spouštíme je neustále. Jen nic nemergujeme jen na jejich slovo.

Skilly fungují i uvnitř subagentů

Subagent je pořád instance Clauda, takže načítá skilly stejně jako vaše hlavní session: porovnává svůj úkol s popisy nainstalovaných skillů a při shodě natáhne tělo. Subagent pro code review s nainstalovaným skillem code review checklist dostane stejný strukturovaný průchod jako v hlavní smyčce, omezený na diff, který jste mu předali.

Tohle se skládá čistě. Subagent řeší, kde se práce odehrává, skill řeší, jak se dělá. Ani jeden nepotřebuje vědět o druhém; skládají se automaticky, dokud jsou oba nainstalované tam, kde na ně subagent vidí – projektové skilly v .claude/skills/, osobní skilly v ~/.claude/skills/. Naše stránka nejlepší programátorské skilly řadí ty, které stojí za instalaci předtím, než zapojíte agenta pro review nebo výzkum.

Subagenti vs. hooky vs. skilly

Tři různé mechanismy, tři různé úlohy, a neustále se pletou dohromady:

	Co dělá	Spouští se na	Kde běží
Skill	Učí Clauda postup nebo styl	Claude porovná váš požadavek s popisem	Uvnitř aktuálního kontextu
Hook	Automaticky spouští pevně daný shellový příkaz	Životní událost (před voláním nástroje, po odpovědi, start session)	Mimo model, deterministicky
Subagent	Deleguje úkol na izolovanou instanci Clauda	Explicitní volání, vámi nebo hlavním agentem	Samostatné kontextové okno

Skill mění jak Claude přistupuje k něčemu, co už stejně udělá. Hook něco vynucuje pokaždé, bezpodmínečně, aniž by se spoléhal na to, že si to model bude pamatovat: spustit testy po každé úpravě, zablokovat commit, pokud se detekují tajemství. Subagent mění kde se práce odehrává, přesouvá ji do jednorázového okna místo vašeho hlavního. Hooky pokrýváme do hloubky, včetně stejného druhu jizev jako výše, v našem průvodci hooky Claude Code.

Skládají se na sebe. Týmové nastavení může používat hook na lintování po každém zápisu, skill na výuku firemního stylu kódu a subagenta na spuštění celého review průchodu před mergem – tři vrstvy, žádná nadbytečná. Pokud ještě sestavujete zbytek svého nastavení, náš průvodce nastavením pro rok 2026 prochází, kam každý díl patří, a náš průvodce tokenovými náklady pokrývá, co všechny tři stojí v klidu.

FAQ

Sdílejí subagenti kontext mojí hlavní session?

Ne, a to je celý smysl. Subagent začíná s prázdnou historií až na prompt, který mu dáte. Nic z vaší hlavní konverzace se automaticky nepřenáší, a nic z toho, co subagent přečte nebo udělá, se nevrací zpátky kromě finálního textu, který vrátí. Pokud potřebuje kontext z vaší konverzace, dejte ten kontext do promptu.

Můžou subagenti běžet paralelně?

Ano. Spuštění několika najednou je standardní vzor pro rozvětvený výzkum a pro nezávislé, nepřekrývající se opravy. Každý dostane vlastní kontextové okno, takže si vzájemně nepřekáží, ale zároveň se nemůžou uprostřed úkolu koordinovat, pokud jste výslovně nepředali výstup jednoho do promptu druhého.

Jak poznám, jestli subagent skutečně udělal to, co tvrdí?

Zkontrolujte artefakt, ne shrnutí. Přečtěte si diff, spusťte test, otevřete soubor. Měli jsme subagenty, kteří hlásili čistý úspěch u práce, která byla částečně nedokončená, ne z nepoctivosti, ale protože shrnutí je rekonstrukce a rekonstrukce se odchylují. Zacházejte s každou zprávou subagenta jako s tvrzením k ověření.

Kde žijí vlastní definice agentů?

.claude/agents/*.md pro agenty na úrovni projektu, kteří cestují s repozitářem přes git, a ~/.claude/agents/*.md pro osobní, dostupné napříč všemi projekty. Každý soubor potřebuje ve frontmatteru minimálně name a description; tools a model jsou volitelné, ale vyplatí se je nastavit záměrně místo ponechání na výchozích hodnotách.

Měl bych omezit, jaké nástroje může subagent používat?

Ano, kdykoli má agent úzkou náplň práce. Agent pro review, který nemůže zavolat Edit, nemůže omylem opravit věc, kterou má kritizovat. Výzkumný agent jen pro čtení, který nemůže zavolat Bash, nemůže omylem spustit něco destruktivního při prohledávání okolí. Pole tools ve frontmatteru agenta je ten mechanismus, a jeho nastavení je levnější než ladit, co s přebytečnou pravomocí udělal přesílený agent.