Claude Code subagenti a worktrees: kdy použít co

Claude Code subagenti dělí práci v jedné session. Každý běží ve vlastním kontextovém okně, udělá jednu úlohu a vrátí shrnutí. Worktrees oddělují úpravy souborů: každá session má vlastní kopii repozitáře a vlastní větev. Naše pravidlo z každodenní práce s paralelními agenty: subagenti jen čtou a každá změna má vlastní worktree, vlastní session a vlastní pull request.

Dnes za nás píše AI veškerý kód a senior ručí za to, co jde do produkce. Paralelní agenti jsou způsob, jak se najednou hýbe víc úloh, aniž by si šlapaly po prstech. Níže je, kdy co používáme, příkaz, který to nese, a co se cestou rozbilo.

Co jsou Claude Code subagenti?

Subagent je pomocník, kterého Claude spustí ve vaší session. Dokumentace Claude Code to říká jednou větou: „Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.“ Každý subagent má tedy vlastní kontextové okno, vlastní systémový prompt, nástroje a oprávnění.

V tom je celý smysl. Subagent přečte hromadu souborů a do hlavní konverzace se vrátí jeden odstavec. Vlastní subagenty si nadefinujete v .claude/agents/: název, popis, nástroje a model. Claude je vybírá podle popisu, nebo si o konkrétního řeknete jménem.

Daní je ten samý odstavec. Vidíte, co subagent nahlásí, ne co přečetl. Pokud něco přehlédl, ze shrnutí to nepoznáte.

Subagenti, nebo worktrees: co na co?

Řeší jiný problém. Subagenti chrání váš kontext. Worktrees chrání vaše soubory. Dokumentace k worktrees popisuje worktree jako samostatnou pracovní složku s vlastními soubory a větví, která sdílí historii repozitáře i remote s hlavní kopií.

Proč naši subagenti jen čtou?

Zapsali jsme to do zadání, které dostane každá session s kódem:

Only you write code. Subagents only read (explore the repo, run a long test suite and return just the failures).

Kód píše jen hlavní session. Subagenti jen čtou: prozkoumají repozitář nebo pustí dlouhé testy a vrátí jen chyby. U psaní dokumentů a QA v prohlížeči je hranice ještě přísnější: „Do it yourself, no subagents.“ Rešerše je opak. Tam zadání škáluje subagenty podle úlohy: jeden na jeden fakt, pár na srovnání, jeden na každou položku u širokého průzkumu. Každý zapíše zjištění do souboru a vrátí jen cestu k němu.

Claude Code umí subagentům dovolit i psát. Stačí přidat isolation: worktree a subagent dostane vlastní dočasný worktree. My přesto držíme jednoho pisatele na úlohu. Recenzent sleduje jeden diff a jednu linii uvažování. Víc pisatelů na jedné úloze znamená víc diffů, které musí někdo sloučit v hlavě.

Jak pouštíme jedno issue v jednom worktree?

Jedna úloha je jeden worktree, jedna větev, jedna Claude Code session a jeden pull request. Orchestrační session zůstává na main v hlavní kopii a větve tam nikdy nepřepíná. Každá změna začíná jedním příkazem wizrd, našeho interního pluginu a CLI pro Claude Code (není veřejný):

wizrd task start <repo> "<brief>"

Co příkaz udělá:

1. Worktree. wizrd worktree new ho vytvoří v jedné složce na worktrees pro celý počítač. Env soubory nalinkuje z hlavní kopie a závislosti nainstaluje podle lockfilu.
2. Kontext. Služba, která žije v repozitáři klienta, dostane worktree celého tohoto repozitáře a službu vnořenou na cestě submodulu. Tak se načte každý CLAUDE.md směrem nahoru. Skilly a agenti z repozitářů nad ní přijdou přes --add-dir.
3. Session. Ve worktree se spustí claude --bg na pozadí. Sledujeme ji v claude agents a když něco potřebuje, píšeme jí zprávou mezi sessions.
4. PR. Session commitne, pushne a otevře pull request ze své větve. Po merge wizrd worktree prune worktree odstraní.

Issue, které dáme našemu AI agentovi, běží stejně, ve smyčce z článku Harness engineering v praxi: AI agent od issue k PR. Stejný kód pro worktrees běží na notebooku člověka i na stroji agenta. Jak si agent před prací sepíše plán, je v článku Claude Code plan mode.

Kdy subagenti pálí tokeny zbytečně?

Každý subagent začíná s čistým kontextem. Nevidí, co hlavní session už přečetla, takže to čte znovu. Když se na stejný modul zeptáte několika subagentů, každý ho čte od nuly.

Na co si dáváme pozor:

• Úloha je malá. Jedno hledání nepotřebuje pomocníka. Shrnutí stojí víc než samotná odpověď.
• Úlohy se překrývají. „Jak funguje přihlášení“ a „kde se kontroluje session“ pošlou dva subagenty do stejných souborů.
• Potřebujete detaily. Review, které musí citovat přesné řádky, se dělá lépe tam, kde ty řádky zůstávají v kontextu.

Řešení je obvykle méně subagentů, ne chytřejší subagenti.

Upřímně: spotřebu tokenů na jednoho subagenta neměříme. Sledujeme kola a aktivní čas na úlohu a tam se plýtvání ukáže. Víc subagentů najednou se nám jasně vyplatí u široké rešerše s nezávislými otázkami a u práce, která by zahltila volajícího. Náš skill na zpracování schůzek běží jako fork (context: fork), takže dlouhý přepis se do kontextu volajícího nikdy nedostane.

Co se rozbilo u worktrees?

Oddělení je ta snadná část. Láme se to na přípravě. Tyhle stojí za to znát:

• Obnovená úloha nedostala svůj worktree. Její větev byla pořád checknutá ve starší složce na worktrees, takže git worktree add selhal. Dnes CLI použije worktree, který větev už má, a jedna složka na worktrees je pro celý počítač pevně daná, pro lidi i pro agenta.
• Příprava env byla až moc snaživá. Linkovala env soubory do prázdných složek submodulů a z příkladů vyráběla .env s náhradními hodnotami. Dnes linkuje jen to, co hlavní kopie opravdu má.
• Větev úlohy posunula ukazatel submodulu. V repozitáři složeném z repozitářů to potichu změní, co dostanou všichni ostatní. Dnes naše brána shodí každou větev úlohy, která ho posune. Ukazatele se hýbou jen přes samostatný sync.
• Paralelní sessions v jedné kopii. Dvě sessions, které ve stejné složce přepínají větve, si navzájem zničí necommitnutou práci. Proto hlavní kopie zůstává na main a nikdo v ní nestaví.

Poslední bod je důvod, proč worktrees vůbec existují. První tři jsou důvod, proč jsme je zabalili do jednoho příkazu místo ručního git worktree add.

Jak začít ve vlastním repozitáři?

Naše CLI nepotřebujete. Základ pokryje Claude Code:

Pak přidejte kontroly, díky kterým se dá paralelní práce bezpečně reviewovat: testy, typy a CI bránu, která musí projít na každé větvi. Hooky, které zastaví nebezpečné příkazy, jsou v našem veřejném Claude Code production starteru. Co patří do pravidel, která čte každá session, je v článku CLAUDE.md a AGENTS.md: pravidla pro AI kód v týmu.

Je váš repozitář připravený na paralelní agenty?

Skutečný limit je review. Náš dispečer nespustí novou úlohu agenta, dokud jeho PR čekají na lidi. Víc paralelních agentů než recenzentů jen prodlouží frontu.

Chcete paralelní agenty v repozitáři vašeho týmu?

Tohle nastavujeme přímo v repozitáři týmu v rámci služby AI-native SDLC pro vývojové týmy: worktrees, pravidla, hooky a kontroly, díky kterým se dají PR od agentů reviewovat. Chybí vám spíš ruce než nastavení? Podívejte se na seniorního vývojáře do týmu. Od roku 2023 jsme dodali 15+ produkčních projektů.

Ozveme se do dvou pracovních dnů a společně vybereme, co vyřešíme jako první.

Pokud si chcete nejdřív promluvit, domluvte si meeting na 15 minut s Filipem.

Kolik agentů dnes váš tým pouští najednou a kdo reviewuje jejich práci?

Časté otázky

Co je subagent v Claude Code?

Pomocník, kterého Claude spustí ve vaší session. Běží ve vlastním kontextovém okně s vlastním promptem, nástroji a oprávněními, udělá jednu úlohu a vrátí shrnutí. Hlavní konverzace zůstane malá.

Jaký je rozdíl mezi subagenty a worktrees?

Subagenti dělí práci v jedné session a chrání její kontext. Worktrees oddělují úpravy souborů: každá session má vlastní kopii souborů a vlastní větev. Subagenty používáme na čtení, worktree na každou změnu.

Mohou subagenti psát kód paralelně?

Mohou. S isolation: worktree dostane každý od Claude Code vlastní dočasný worktree. My přesto držíme jednoho pisatele na úlohu, protože recenzent sleduje jeden diff a jednu linii uvažování mnohem lépe než několik.

Jak spustím Claude Code ve worktree?

Příkazem claude --worktree <název>. Claude Code vytvoří worktree v .claude/worktrees/ na nové větvi. Přidejte .claude/worktrees/ do .gitignore a env soubory, které čerstvá kopie potřebuje, vypište v .worktreeinclude.

Kdy subagenti pálí tokeny zbytečně?

Když je jejich úloha malá nebo se překrývá s jinou. Každý subagent začíná s čistým kontextem, takže znovu čte, co hlavní session už přečetla. Víc subagentů najednou se vyplatí u široké rešerše s nezávislými otázkami.