Claude Code subagent: model, auto-compact a nižší náklady

Claude Code subagent je nejlevnější pracovní síla, kterou máš k dispozici — dokud nezjistíš, že ti delegované úkoly umírají na plném kontextovém okně a že noční dávkové běhy shodí přetížené API. Verze 2.1.296 (9. 10. 2026) přidala přesně ty provozní kontroly, které ti chyběly: samostatný model pro workflow agenty, dřívější auto-compact subagentů a delší retry při přetížení. V tomto návodu si subagenta vytvoříš od nuly a nastavíš mu všechno, co potřebuje pro dlouhé a levné běhy.

Tip Návod platí pro Claude Code 2.1.296 a novější; v době publikace (21. 10. 2026) je aktuální verze 2.1.306 a všechny popsané proměnné i políčka autoCompactWindow jsou v changelogu pořád zdokumentované.

Nejde o okrajovou fintu. Subagent s vlastním kontextovým oknem ti šetří hlavní konverzaci — ta nemusí nést tucty přečtených souborů z průzkumu a ty můžeš paralelně řešit víc úkolů. Ale bez nastavení modelu a kompaktu jede každý subagent na výchozí konfiguraci a jeho náklady i životnost řídí náhoda. O strategii „který model pro kterou roli" jsme psali v článku o trimodelovém workflow v Claude Code a o routingu za účelem úspory v návodu jak ušetřit na Claude Code — dnešní tutoriál se věnuje provozu: jak subagenta postavit, nastavit a udržet při životě.

01K čemu je Claude Code subagent

Subagent je samostatný agent s vlastním kontextovým oknem, vlastním systémovým promptem a vlastní sadou nástrojů. Hlavní konverzace mu deleguje úkol, on ho odevzdá a její kontext zůstane čistý. V praxi to vypadá takto: necháš si od Sonnetu napsat funkci, a místo aby si hlavní agent sám četl třicet souborů, zavolá subagenta „projdi související kód a najdi místa, kde se to má upravit". Ten vrátí shrnutí, hlavní agent pokračuje s čistou hlavou.

Typické role pro vlastní subagenty:

• reviewer kódu — po každé změně projde diff a navrhne vylepšení
• průzkumník — hledá v kódu, logách nebo dokumentaci
• specialista na testy — píše a pouští testy k hotové funkci
• analytik dat — čte exporty a vrací závěry

Vestavěné jsou dva: Explore pro rychlý průzkum kódu a Plan pro plánování úkolů. Oba běží na úspornějším nastavení — Explore navíc přeskakuje načtení CLAUDE.md, aby byl rychlý a laciný.

Subagent ale není řešení na všechno. U krátkého úkolu, který zvládneš jedním promptem v hlavní konverzaci, delegování jen přidá režii: spawn agenta, předání kontextu, čekání na výsledek. Delegování se vyplatí u práce, která má hodně vstupů (soubory, logy, výpisy) a úzký výstup (souhrn, verdikt, seznam míst k úpravě) — to je kombinace, kde čistý kontext subagenta vydělá nejvíc.

Paralelní nasazení víc agentů najednou řeší Claude Code projekty a paralelní thready; tady se věnujeme jedné věci: aby jeden subagent dobře a levně odvedl svou práci.

02Vytvoření prvního subagenta

Subagent je markdown soubor s YAML frontmatterem. Nemusíš ho psát ručně — nech to na Claude samotném.

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

---
name: code-improver
description: Scans files and suggests improvements for readability,
  performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

03Jak nastavit subagentovi model

Políčko model ve frontmatteru řídí, na čem subagent poběží. Akceptuje tři formy:

• alias: sonnet, opus, haiku nebo fable
• plné ID modelu: například claude-opus-5-5 (stejné hodnoty jako přepínač --model)
• inherit: stejný model jako hlavní konverzace

Claude Code vybírá model subagenta v tomto pořadí (podle oficiální dokumentace subagentů, stav k říjnu 2026):

1. model předaný při konkrétním volání (per-invocation parametr)
2. políčko model ve frontmatteru subagenta
3. proměnná CLAUDE_CODE_SUBAGENT_MODEL
4. model hlavní konverzace

Prakticky: frontmatter vyhrává nad proměnnou prostředí. Chceš-li pro jednoho subagenta Haiku, nastav mu model: haiku a je to. Který model pro kterou roli zvolit — Haiku na průzkum, Opus na plánování — rozbourává článek o trimodelovém workflow; tady nás zajímá provoz.

Detail, který se hodí vědět: když tvoje organizace přes availableModels allowlist model zablokuje, Claude Code ho tiše nahradí povoleným a v interaktivním režimu tě na substituci upozorní. U sdílených týmových nastavení kontroluj po změnách /tasks, na jakém modelu subagent reálně běží.

04Jeden model pro celý workflow

Když máš subagentů víc, nastavovat model každému zvlášť je nekonečná práce. Na to jsou proměnné prostředí — a tady přichází novinka z verze 2.1.296 (changelog, 9. 10. 2026).

Třetí řádka je nová a řeší případ, který dřív nešlo vyřešit čistě: workflow agenty chceš srazit na levný model, ale běžným subagentům v konverzaci necháš jejich individuální nastavení z frontmatteru. Dřív jsi musel buď přepisovat definice, nebo použít _FORCE, což vztáhlo změnu na všechno.

Nastavení patří do env bloku v settings souboru:

{
  "env": {
    "CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL": "haiku"
  }
}

Kombinace CLAUDE_CODE_SUBAGENT_MODEL + _FORCE=1 (vynucení jednoho modelu úplně všude) funguje jako dřív — podrobnosti a hotovou konfiguraci ke zkopírování najdeš v návodu jak ušetřit na Claude Code.

Pozor _FORCE je velká páka — ignoruje model ve frontmatteru i model předávaný při volání. Pro většinu použití je rozumnější WORKFLOW_SUBAGENT_MODEL pro automatizace plus model: ve frontmatteru pro konkrétní agenty.

05Auto-compact: ať subagent nepřeteče kontextem

Dlouho běžící subagent dřív nebo později zaplní kontextové okno. Okamžik auto-compactu přitom dřív vycházel z okna hlavní konverzace — u subagenta, který čte velké soubory nebo dlouhé logy, tak kompakt míval přijít později, než bylo pro jeho práci zdravé, a přetečení ho zastavilo uprostřed úkolu.

Od verze 2.1.296 můžeš přidat do frontmatteru subagenta (nebo do definic přes --agents) políčko autoCompactWindow, aby se subagent komprimoval dřív, než se naplní okno hlavní konverzace:

---
name: log-analyzer
description: Čte velké logy a hledá chyby
model: haiku
autoCompactWindow: 150000
---

Hodnota se udává v tokenech, stejně jako u globálního nastavení auto-compact (rozsah 100 tisíc až 1 milion; fungují i zápisy jako 500k). Subagent si shrne hotovou práci dřív, ať má po kompaktu stále vzduch na dokončení úkolu.

K tomu patří druhá novinka ze stejné verze: možnost allow_large u nástroje Read. Když subagent potřebuje načíst celý velký soubor najednou a kontext na to má, udělá to v jednom volání místo rozkouskování. U analytických úkolů na levném modelu to ušetří zpáteční cesty i tokeny.

06Co s chybou 529 a jak hlídat náklady

Přetížené API (HTTP 529) je realita, když spustíš víc paralelních agentů — přesně v momentě, kdy ti automatizace nejvíc vydělává. Claude Code sám opakuje pokusy s rostoucí prodlevou, ale defaultní maximum backoffu je krátké na to, aby přečkal delší špičku. Nová proměnná CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS (opět 2.1.296) ti dovolí nastavit delší maximální prodlevu mezi pokusy, hodnota je v milisekundách — pro noční běhy zkus 600000 (10 minut). Patří do stejného env bloku jako modely. U nočních běhů, kde ti na latenci nezáleží, to znamená místo přerušeného workflow dokončenou práci. Když běh poběží celou noc bez dohledu, kombinuj tyto proměnné s Claude Code headless a retry watchdogem, který chyby 429 a 529 opakuje bez omezení.

Na náklady dohlédneš třemi způsoby:

• příkaz /cost ukáže náklady session včetně subagentů
• --max-budget-usd zastaví běh, když účet přeroste limit
• status line ti náklady ukazuje průběžně

Výpočty v těchto výpisech navíc od 2.1.296 počítají cache reads u Sonnetu 5.5 za polovinu — 0,10 $ za milion tokenů místo dosavadních 0,20 $. Subagenti, kteří znovu čtou tytéž soubory, tak mírně zlevní i bez změny nastavení. Kompletní přehled tarifů najdeš v ceně Claude Code pro rok 2026.

Chceš-li chování agentů přizpůsobit ještě hlouběji než přes proměnné prostředí, mrkni na Claude Code mods nebo automatizaci přes hooks.

Kontrola před nasazením

Než subagenta pustíš do ostrého workflow, projdi si tento checklist:

• model: /tasks ukazuje, na čem subagent reálně běží (ať tě nepřekvapí allowlist substituce)
• nástroje: pole tools odpovídá záměru — read-only agenti opravdu nemají Edit ani Write
• kompakt: u dlouhých úkolů má autoCompactWindow nastavenou hodnotu, jinak subagent jede podle okna hlavní relace
• rozpočet: --max-budget-usd je nastavené u automatizací, kde může běh nafouknout účet

07Časté otázky