Subagent jako samostatné okno pozornosti

1. Co je subagent a k čemu slouží

Subagent je specializovaný pomocník, kterému Claude Code předá úkol: pracuje ve svém vlastním kontextovém okně a do vaší relace vrátí krátké shrnutí. Čtení souborů, hledání a volání nástrojů zůstávají v jeho kontextu.

Proč právě takhle: v hlavní relaci zabírají zprávy, přečtené soubory a výsledky příkazů místo v jednom okně, a jeho kapacita není nafukovací. Jak se okno plní, Claude Code zkracuje historii a část podrobností se může ztratit. Subagent umožňuje přesunout dílčí práci do samostatného okna a v hlavním rozhovoru nechat jen její výsledek.

Nejjednodušší subagent

Pro první spuštění stačí obyčejná zpráva v Claude Code: výslovně požádejte o vyvolání subagenta a popište jeho úkol. Vlastní soubor role dopředu vytvářet nemusíte, na takovou práci postačí vestavěný pomocník. Například:

Vyvolej subagenta pro čtení souboru index.html.
Ať sestaví krátkou mapu souboru: hlavní sekce
a co dělá každá z nich. Pak napíše stručné shrnutí
obsahu ve 3-5 větách.
Soubor neupravovat. Vrať odpověď subagenta do této relace.

Hlavní agent předá úkol pomocníkovi a po dokončení ukáže jeho odpověď ve vašem rozhovoru. Při běhu na pozadí se dole, pod polem pro zadávání, objeví lišta se jménem subagenta a stavem jeho práce. Klikněte na ni, abyste otevřeli relaci subagenta a viděli, co čte a dělá. Během práce ověřte, že se opravdu spustil samostatný běh subagenta: prosba obyčejným textem nasměruje volbu Claude, ale sama o sobě delegování nezaručuje.

Co subagent dostává

Pokud potřebujete stejný úkol opakovat se stálými pravidly, můžete popsat vlastní roli v souboru. Na startu má takový subagent dva hlavní vstupy:

• instrukci role z vašeho konfiguračního souboru - specializaci a pravidla chování;
• popis úkolu, který hlavní agent sestaví podle vašeho požadavku.

Claude Code k nim sám přidá společné pozadí: soubory CLAUDE.md projektu, snímek git status a údaje o prostředí. Váš rozhovor s hlavním agentem mezi tím není.

Na schématu je důležité jedno: subagent splní úkol ve svém okně a do hlavního rozhovoru vrátí shrnutí. Hlavní agent nemusí načítat všechna dílčí čtení a hledání. Samotné shrnutí přitom taky zabírá místo v hlavním kontextu.

Takové rozdělení má odvrácenou stranu: shrnutí neukazuje celou cestu k závěru. Z něj snadno přehlédnete, jaká data pomocníkovi chyběla nebo co nechal neověřené. Proto odpověď potřebuje odůvodnění a omezení, a její závěry se vyplatí ověřit.

Proč si Claude nepamatuje všechno

Kontextové okno - údaje, kterými model disponuje při přípravě další odpovědi: instrukce, dostupná historie rozhovoru, přečtený kód, výsledky příkazů. Právě proto se agent může opřít o rozhodnutí, které jste probrali o několik zpráv dřív. Okno má svůj limit; neuchovává celý rozhovor do všech podrobností navždy.

Na screenshotu příkaz /context ukazuje 4k/200k tokens (2%): obsazeno je asi 4 tisíce tokenů z 200 tisíc dostupných. Token je malý úsek textu: slovo, část slova nebo znak. Proto 200 tisíc tokenů neznamená 200 tisíc slov. Tohle je velikost okna zobrazené relace; u jiného modelu nebo konfigurace se může lišit.

Níže vidíte, co zabírá místo: System prompt - systémové instrukce, Memory files - načtené soubory paměti a pravidel, Skills - údaje o skillech, Messages - zprávy. Konverzace tu skoro žádná není, ale část okna už zabírají instrukce. Řádek Free space: 196k (98.0%) ukazuje zbylé volné místo. S pokračujícím rozhovorem, čtením souborů a spouštěním příkazů ho ubývá.

Dál si tento mechanismus rozebereme na vlastním reviewer pro čtení kódu: jaké údaje dostává a jak vytvořit soubor jeho role. Tady jde o nové běžné spuštění; způsoby, jak pokračovat v předchozí práci nebo předat kopii historie, v tomto příkladu nepotřebujeme.

2. Co reviewer ví o projektu

Samostatný kontext neznamená, že pomocník neví nic. Má počáteční instrukce a přístup k projektu. Tady je, odkud bere údaje vlastní reviewer z našeho příkladu:

CLAUDE.md je soubor s obecnými instrukcemi pro Claude Code: například kde leží zdrojový kód a jaké konvence projekt dodržuje. Vytvářet ho zvlášť kvůli téhle kontrole nemusíte.

Historie vašeho rozhovoru se nepřenáší automaticky. Pokud hlavní agent už četl app.js, obsah tohoto čtení se u reviewer sám od sebe neobjeví. Ale soubor nikam nezmizel: pomocník ho může otevřít znovu.

S rozhodnutími z chatu je to stejné. Řekněme, že jste se domluvili, že dva stejné názvy v seznamu mají zůstat oddělenými nákupy. Pro kontrolu mazání je to podstatný požadavek. K reviewer se dostane, pokud ho hlavní agent zahrne do zadání nebo pomocník přečte dokument, kde je zapsaný.

3. Vytváříme soubor role

Roli umístíme do .claude/agents/reviewer.md uvnitř projektu. Do uživatelské složky ~/.claude/agents/ lze ukládat i role dostupné napříč projekty; znak ~ označuje domovskou složku uživatele. Zatím stačí projektová varianta.

Soubor můžete vytvořit tak, že o to požádáte Claude Code:

Vytvoř .claude/agents/reviewer.md pro kontrolu kódu stránky
bez úprav. Povol jen Read, Grep, Glob.
Reviewer vrací podložená zjištění, zkontrolovaný rozsah
a omezení; žádná zjištění jsou přípustný výsledek.
Ukaž vytvořený soubor.

Výsledkem by měl být obyčejný textový soubor. Žádná magie. Níže je hotová varianta: můžete s ní porovnat odpověď agenta, nebo ji uložit sami. Pokud roli s takovým jménem už máte, nejdřív se podívejte na její obsah, ať nenahradíte potřebnou instrukci.

---
name: reviewer
description: Kontroluje kód hotové stránky kvůli chybám v chování a vrací podloženou zprávu. Použít, když je potřeba review stránky bez oprav.
tools: Read, Grep, Glob
---
Prostuduj kód uvedených souborů podle zadaných požadavků.
Neupravuj soubory. Neslibuj spuštění stránky: máš jen čtení a hledání.
Ke každému zjištění uveď místo, očekávané chování, odůvodnění závěru,
podmínky kontroly a dopad. Pokud údaje chybí, označ to.
Zvlášť vyjmenuj, co jsi zkontroloval a co ne.
Pokud jsi podle zadaných kritérií problémy nenašel, tak to napiš.

Blok mezi dvěma řádky --- se nazývá frontmatter: nastavení na začátku Markdown souboru. Tady name zadává jméno role, description vysvětluje hlavnímu agentovi, kdy ji vybrat, a tools vyjmenovává dostupné nástroje. Pod ním následují obyčejné instrukce slovy.

Tři nástroje v příkladu dělají přesně to, co je pro prohlížení kódu potřeba: Read čte soubor, Grep hledá podle obsahu, Glob najde soubory podle jména nebo cesty. Reviewer proto najde funkci mazání a přečte ji, ale nespustí stránku v prohlížeči ani nevykoná příkaz v terminálu.

Řádek "neupravuj soubory" popisuje úkol. Pole tools omezuje prostředky, jimiž ho lze splnit. Necháte-li v textu jen prosbu a nástroje neomezíte, pomocníkovi může zůstat možnost zápisu. V hotovém příkladu jsou obě části už na místě, dodatečně omezení přidávat netřeba.

Soubor role vypadá podobně jako skill: nastavení a text instrukce. Snadno se dají splést. Tady ale nastavujeme samostatné spuštění pro kontrolu. Skill obvykle přidává opakovatelný postup do aktuálního rozhovoru, ačkoli skilly se taky mohou spouštět v samostatném kontextu. Vybírejte podle toho, jak se má práce provést, ne podle podobného vzhledu obou souborů.

4. Kontrolujeme a voláme reviewer

Soubor na disku je první výsledek. Teď zkontrolujeme, jestli ho relace vidí. Otevřete soubor a podívejte se na jméno reviewer, popis, řádek nástrojů a text: neslibuje se tam spuštění prohlížeče nebo rovnou oprava chyb?

Do pole pro zadávání Claude Code napište @ a vyberte reviewer s označením agent. Potřebujete právě roli, ne podobnou položku s cestou k souboru. Výběrem ze seznamu výslovně určíte pomocníka pro tento úkol.

Pokud role chybí, nejdřív zkontrolujte cestu: soubor musí ležet v .claude/agents/ otevřeného projektu. Pak frontmatter: oba oddělovací řádky, jméno a popis. Můžete taky požádat Claude Code, ať soubor s definicí role zkontroluje sám.

Podle dokumentace Claude Code se změny v už sledované složce projeví během pár vteřin. Pokud se složka agents objevila poprvé až po startu relace, je potřeba restart. Ukončete aktuální relaci a pak v obyčejném terminálu, ze stejné projektové složky, spusťte:

claude --continue

Tak budete pokračovat v posledním rozhovoru z aktuálního adresáře. Po spuštění znovu zkontrolujte seznam @. Samotný příkaz pro spuštění Claude se píše do terminálu po ukončení relace, ne do už běžícího rozhovoru.

Pro první úkol vezmeme stránku se seznamem nákupů: značkování v index.html, logika v app.js, oba soubory v kořeni projektu. Ve svém projektu nahraďte cesty a očekávané chování svými. Po výběru reviewer ze seznamu přidejte ke zmínce tento text:

Prostuduj index.html a app.js v kořeni projektu.
Zkontroluj přidávání a mazání položek: čítač musí souhlasit
s počtem zbylých položek, smazání jednoho záznamu nesmí
odstranit jiný se stejným názvem.
Soubory neupravuj. Vrať závěry ohledně kódu a co je potřeba zkontrolovat v prohlížeči.

Tady už je všechno pro úzkou kontrolu: kde hledat, co by se mělo dít a jaký výsledek je potřeba. Brief v samostatném souboru tu není potřeba. Hlavní agent zformuluje úkol pro vybraného reviewer; samotný výběr přes @ určuje, kdo úkol provede, ale nezaručuje doslovné předání vaší zprávy.

5. Jak přichází výsledek

Po odeslání požadavku se podívejte, jestli se spustil běh reviewer. V běžné interaktivní relaci může taková práce probíhat na pozadí: vidíte ji v panelu a můžete pokračovat v rozhovoru. Příkazem /tasks si zobrazíte úkoly, včetně nedávno dokončených.

Až kontrola skončí, hlavní agent dostane výsledek a sdělí vám ho. Pokud je shrnutí příliš krátké, požádejte: "Ukaž mi závěrečnou zprávu reviewer celou". Tak se snáz zachová přesná formulace zjištění i omezení kontroly.

Například výuková zpráva o čítači by mohla vypadat takto:

Zkontroloval jsem přidávání a mazání v app.js.
V removeItem() se seznam překreslí, ale volání updateCounter()
na této cestě jsem nenašel. Očekává se, že čítač ukáže počet
zbylých záznamů.
Kontrola v prohlížeči: přidat jednu položku, smazat ji,
porovnat čítač s prázdným seznamem.
Mazání záznamů se stejným názvem jsem zvlášť nekontroloval.
V prohlížeči jsem nic nespouštěl.

Je to ukázka podoby odpovědi, ne slib, že na své stránce najdete přesně takový bug. Náš reviewer umí jen číst kód, takže poslední řádek poctivě popisuje jeho možnosti. Závěr o kódu může být podložený i bez spuštění, ale jeho odůvodnění je potřeba ověřit: třeba jestli čítač neaktualizuje jiná funkce na stejné cestě.

Otevřete uvedené místo nebo zopakujte popsané akce v prohlížeči. Pokud se problém potvrdí, můžete opravu zadat hlavnímu agentovi. Pokud ne, popište, co jste zjistili, a požádejte o přezkoumání závěru. Pěkně zformátovaná zpráva ještě nerozhoduje, co přesně je potřeba měnit.

Odpověď "podle zadaných kritérií jsem problémy nenašel" je taky přípustná, pokud je jasné, co bylo zkontrolováno. Kdežto "nenašel jsem soubor s logikou mazání" znamená částečný výsledek: nejdřív je třeba upřesnit cestu. Doplňovat zprávu dohady jen kvůli počtu nemá smysl.

Mimochodem, v seznamu se mohou objevit i vestavěné role Explore a Plan. Jsou dostupné bez vytváření vlastních souborů rolí.

6. Kdy se vyplatí delegovat

Po první úspěšné kontrole snadno dostanete chuť mít na každou akci samostatného pomocníka. Pokušení je pochopitelné. Nové spuštění ale musí něco přinést: nezávislý pohled nebo samostatnou práci, jejíž podrobný průběh v hlavním rozhovoru nepotřebujete.

Několik závislých kroků taky může tvořit jeden úkol pro subagenta. Najít handler, zkontrolovat jeho volání a sestavit závěr - to je normální ucelený úkol. Nevyplatí se jen rozdávat každý krok samostatnému pomocníkovi, pokud pak budete muset všem znovu vysvětlovat výsledky sousedního kroku.

Model pro subagenta lze přiřadit zvlášť polem model. teď ho nepotřebujeme: nejdřív se vyplatí získat srozumitelnou roli a ověřitelný výsledek. Samostatné spuštění samo o sobě neznamená ani silnější, ani slabší model.

Druhá role musí kontrolovat něco jiného

Řekněme, že kromě reviewer potřebujete playtester pro kontrolu uživatelského scénáře. Kopie dosavadní instrukce s novým jménem skoro nic nezmění. Nejdřív rozlište předmět práce a výsledek:

Například role může rozebírat jen smazání jednoho ze dvou nákupů se stejným názvem: po akci by měl zůstat jeden záznam a čítač by měl ukazovat 1. Je to měřitelný úkol. "Posuď, jestli je stránka dobrá" nechává příliš mnoho prostoru pro rady podle vkusu.

Teď porovnejte úkol s nástroji. Jen se čtením a hledáním, jako má náš reviewer, pomocník v prohlížeči nic neprovede. Může sestavit scénář kontroly nebo rozebrat vaše zapsaná pozorování. To je příprava nebo analýza kontroly, ne samostatně provedený playtest.

Připrav scénář kontroly smazání jednoho ze dvou nákupů
se stejným názvem. Pro každý krok uveď akci
a očekávaný výsledek. Kód neupravuj, provedení netvrď.
Po mých pozorováních porovnej očekávané se skutečným
a vyjmenuj, jaká data chybí.

Pro samostatné spuštění je potřeba dostupný nástroj pro práci s prohlížečem a ověření, že se spuštění opravdu uskutečnilo. Samotné jméno playtester na to nestačí. Nejdřív zvolte způsob kontroly, pak v roli popište, kdy ji volat a jaký výsledek může poctivě vrátit.

7. Jak to vypadá ve vaší relaci

Teď máte soubor role, kterou relace vidí, a krátkou kontrolu, kterou jí můžete zadat. To na začátek stačí. Nemusíte si předem připravovat desítku podobných rolí jako reviewer.

Dál upravujte tu vrstvu, ve které se problém objevil. Nepředali jste důležitou podmínku - doplňte zadání. Dostali jste pochybný závěr - zkontrolujte odůvodnění. Reviewer pravidelně vrací příliš obecné odpovědi - upřesněte instrukci role. Soubor zůstane v projektu a další kontrolu už začnete s těmito pravidly.

Pro opakované úkoly se bude hodit brief pro reviewer. Když už máte odpověď, přejděte ke kontrole zjištění a výběru oprav.