Jak svěřit review subagentovi a ověřit jeho zprávu

Požadavek "Zkontroluj stránku" nechává na recenzentovi řadu rozhodnutí: hledat chyby v chování, hodnotit vzhled, nebo navrhovat jiný způsob, jak kód napsat. Výsledkem může být úhledný seznam poznámek, který vám s vaším úkolem skoro nepomůže. Podívejme se, jak subagentovi Claude Code předat srozumitelné zadání a pak ověřit, zda je splněno.

Pokud reviewer ještě není nastavený, nejprve vytvořte roli a spusťte ji poprvé. Tady se zaměříme na samotné zadání a úplnost odpovědi.

1. Co předat recenzentovi

Recenzent kontroluje cizí práci a vrací poznámky s odůvodněním. V našich příkladech je to nastavený vlastní subagent s názvem reviewer, který smí soubory jen číst a prohledávat: Read, Grep, Glob. Kód studuje, ale neopravuje ho a stránku v prohlížeči nespouští. Samotný název reviewer takovou roli automaticky nevytvoří: předpokládáme, že ve vašem projektu už nastavená je.

Při novém běžném spuštění takový subagent automaticky nedostane celou historii vaší konverzace. Hlavní agent, se kterým komunikujete, pro něj sestaví samostatné zadání. Proto se důležitý požadavek typu "dva nákupy se stejným názvem jsou různé záznamy" musí dostat do zadání nebo do dokumentu, který má recenzent za úkol přečíst. Tento postup popisuje dokumentace ke kontextu subagentů; tady jde o spuštění vlastní role, ne o fork s kopií konverzace.

Porovnejte "Podívej se na projekt" a "Zkontroluj mazání záznamů a aktualizaci čítače; kód neměň". Ve druhém případě už je jasné, kam se dívat a jakou akci nečekáte. Zbývá upřesnit, co se považuje za správný výsledek.

Na krátkou jednorázovou kontrolu stačí zpráva. Pokud je kritérií hodně nebo se kontrola bude po opravách opakovat, je pohodlnější uložit si brief: krátký popis úkolu vedle projektu. Žádná samostatná specifikace na deset stran. Pár podmínek, bez kterých by recenzent musel hádat.

Všechny otázky předvídat nejde, a ani to není potřeba. Když vstupní údaje nestačí, má recenzent mezeru ve zprávě označit. Hlavní agent si ji pak může upřesnit u vás. Dobré zadání snižuje nejasnosti, ale dobrou odpověď nezaručuje: model se může splést i u jasného úkolu.

2. Čtyři části zadání

Cíl odpovídá na otázku, jaké chování je třeba zkontrolovat. Pro stránku se seznamem nákupů je to přidávání, mazání a čítač záznamů. "Vylepšit projekt" je příliš široké: není jasné, jaké vylepšení je teď důležité.

Vstup určuje soubory a očekávané chování. Samotná cesta k app.js nestačí, pokud z kódu nejde poznat, zda jsou stejné názvy povolené. Toto produktové rozhodnutí je potřeba předat výslovně. Rovnou také uveďte, čím kontrolovat: u nás je to jen čtení kódu, bez prohlížeče.

Hranice oddělují tuto kontrolu od sousedních úkolů. Například styly, mobilní zobrazení a ukládání seznamu mezi relacemi teď neřešíme. soubory neměníme. Pokud potřebný soubor chybí, zastavíme část kontroly, která na něm závisí, a oznámíme to, místo abychom si jeho obsah vymýšleli.

Výsledek popisuje, co chcete dostat: zkontrolovaný rozsah, podložená zjištění a omezení. Nechtějte, aby recenzent za každou cenu našel pět chyb. Doporučení Claude Code k review na riziko takového zadání zvlášť upozorňují: úkol hledat nedostatky vede k poznámkám i tam, kde je práce odvedená správně.

Každá větev přidává něco, co ostatní nedají: cesta k souboru neurčuje očekávané chování a cíl nestanoví zákaz úprav. Dejte tyto podmínky dohromady, aby je recenzent mohl při kontrole porovnat.

Místo "Zkontroluj stránku se seznamem nákupů" tedy předáme následující zadání. Můžete ho poslat zprávou, nebo uložit do REVIEW_BRIEF.md v kořeni projektu:

# Kontrola seznamu nákupů
Cíl: zkontrolovat v kódu přidávání, mazání a čítač.
Vstup: index.html a app.js v kořeni projektu.
Očekává se: přidaná položka se objeví v seznamu;
čítač se rovná počtu položek; smazání jednoho záznamu
nesmaže jiný záznam se stejným názvem.
Hranice: soubory neměň; styly, mobilní zobrazení a ukládání
seznamu mezi relacemi do této kontroly nepatří.
Pokud chybí potřebný soubor nebo požadavek, uveď mezeru,
nedomýšlej si ji a vrať výsledek za dostupnou část.
Výsledek: drž se formátu role reviewer; uveď, co je zkontrolováno
a co zůstalo nezkontrolováno. Výsledek bez zjištění je přípustný.

Formát role reviewer si rozebereme hned níže. Pokud vaše role trvalý formát ještě nemá, můžete ho zahrnout do téže jednorázové zprávy. Názvy polí nejsou povinné: důležité jsou informace, na které vám pomáhají nezapomenout.

Požadavek "ve zprávě nejdřív ukaž tři nejzávažnější zjištění" omezuje rozsah odpovědi, ne hloubku kontroly. Pokud takový limit potřebujete, požádejte zvlášť, aby recenzent uvedl, zda existují další zjištění. Zastavit se po třetí poznámce a prohlásit úkol za zkontrolovaný nelze.

3. Co uložit do souborů

Podmínky konkrétního úkolu se mění: dnes kontrolujeme čítač, zítra ukládání seznamu. Ty patří do briefu. Požadavek ukázat místo chyby a odůvodnění se ale hodí skoro u každého review. Ten je pohodlnější zapsat jednou do instrukcí role.

Output contract, neboli kontrakt výsledku, tu znamená dohodnutý formát odpovědi. Zní to vážněji, než to ve skutečnosti je: jde o běžné instrukce pro recenzenta, ne o zvláštní nastavení Claude Code ani o automatickou kontrolu kvality. Formát pomáhá najít ve zprávě potřebné informace, ale jejich správnost nezaručí.

Dvě horní větve odpovídají za různé věci: brief určuje obsah kontroly, instrukce role mimo jiné podobu zprávy. Aby recenzent uložený brief použil, zadejte mu, ať soubor přečte. Sám se do něj nepodívá. Dole vznikne zpráva, u které je ještě potřeba posoudit odůvodnění a úplnost.

Tady je oddíl, který můžete přidat do textové části už existujícího souboru role .claude/agents/reviewer.md, za jeho nastavení:

## Formát výsledku
Uveď zkontrolované soubory a kritéria.
Ke každému zjištění: místo, očekávané chování, odůvodnění,
podmínky kontroly a dopad; prioritu zdůvodni.
Odděluj to, co potvrzuje kód, od neověřených předpokladů.
Zvlášť vyjmenuj omezení a chybějící údaje.
Pokud jsi podle kritérií problémy nenašel, napiš to.

Toto je úryvek instrukcí, ne celý soubor subagenta. Naše role smí jen číst a vyhledávat, takže trvalé pole "změněné soubory" nepotřebuje. V obsáhlejší zprávě musí údaje o změnách odpovídat skutečnosti: nelze předem předepsat řádek "změněné soubory: žádné" bez ohledu na to, co se stalo.

Když je brief uložený, pošlete hlavnímu agentovi takový požadavek:

Zadej roli reviewer, ať přečte REVIEW_BRIEF.md v kořeni projektu
a zkontroluje uvedené soubory podle jeho kritérií.
Vrať celou výslednou zprávu.

Výslovně jsme zadali dokument přečíst, ne ho jen zmínili. Samotný soubor ale nic nezaručuje: recenzent může podmínku i tak přehlédnout. Uložený brief je užitečný tím, že s ním můžete výsledek porovnat a kontrolu zopakovat. Když se požadavky změní, nejdřív aktualizujte dokument, jinak další průchod bude hodnotit starý úkol.

4. Jak ověřit zprávu

Nejdřív se podívejte, co bylo opravdu zkontrolováno. V briefu bylo přidávání, mazání, čítač a nezávislost záznamů se stejným názvem. Pokud zpráva mluví jen o čítači, ještě to není výsledek za celý úkol. I kdyby bylo jediné zjištění naprosto správné.

Pomáhá porovnat každé kritérium briefu s odpovědí. V cvičné neúplné zprávě to například vyšlo takto:

Chybějící řádek o stejných názvech neznamená, že tam chyby nejsou. A jedno podložené zjištění o čítači nevynahradí vynechanou část zadání. Vraťte zprávu s konkrétním upřesněním:

V briefu je smazání jednoho ze dvou záznamů se stejným názvem.
Ve zprávě toto kritérium chybí. Zkontroluj ho dostupnými prostředky
a uveď odůvodnění výsledku, nebo důvod, proč jsi ho zkontrolovat nemohl.
Ostatní závěry beze změn opakovat nemusíš. Kód neměň.

Zvlášť posuďte věrohodnost podstatných zjištění: porovnejte uvedené místo, požadavek a odůvodnění závěru. Podrobný příklad najdete v článku o čtení zprávy z review. Tady jsou potřeba obě kontroly: pokrytí zadání a podloženost výsledku. Navržený scénář spuštění ještě není provedený test.

Na první rozcestí rozhodujeme, zda je pro náš úkol zkontrolováno dost. Pokud ne, vyžádáme si chybějící část, nebo přijmeme jen tu zkontrolovanou, ale i u ní posoudíme odůvodnění. Na druhém rozcestí oddělujeme podložené závěry od sporných a nesprávných. Nejasné odůvodnění stojí za upřesnění; prokazatelně nesprávnou poznámku nebo radu mimo zadání můžete odmítnout.

I zpráva bez zjištění může touto kontrolou projít. Například: "Zkontrolovány cesty přidání a mazání, nezávislost stejných záznamů a aktualizace čítače v index.html a app.js. Podle těchto kritérií jsem problémy nenašel; v prohlížeči jsem nespouštěl". Takový závěr neslibuje, že v projektu nejsou žádné chyby. Hlásí výsledek v uvedených mezích, a když je potřeba, klíčové cesty si ověříte sami.

Naproti tomu "Nenašel jsem app.js na uvedené cestě, chování mazání jsem ověřit nemohl" znamená nedostatek údajů, ne absenci chyb. Tady je potřeba předat správnou cestu a pokračovat v kontrole. Krátká poctivá odpověď je užitečnější než dlouhá zpráva, ve které je mezera schovaná.

Přijmout zprávu neznamená zadat opravu všeho, co je v ní uvedeno. Uznali jste výsledek kontroly za podložený; jaké změny udělat teď, rozhodujete zvlášť.

5. Když je potřeba další průchod

Pokud ve zprávě chybí odůvodnění, nemusíte začínat review od začátku. Vraťte konkrétní mezeru. Řekněme, že zkrácená verze zjištění o čítači obsahuje jen název chyby, bez rozboru volání. Požadavek hlavnímu agentovi pak může vypadat takto:

Vrať roli reviewer zprávu k upřesnění: ve zjištění o čítači
chybí cesta, kudy se čítač po smazání aktualizuje.
Ať tuto cestu zkontroluje a doplní odůvodnění závěru.
Kód neměnit.

Pokud se ukáže, že aktualizace už probíhá v jiné funkci, poznámku je potřeba stáhnout. Nehledat za ni náhradu jen kvůli původnímu počtu bodů. Pokud se chyba potvrdí, můžete opravu zadat hlavnímu agentovi samostatným požadavkem a uvést konkrétní zjištění a přípustný rozsah změn.

Po opravě se vyplatí další průchod podle stejného briefu:

Zadej roli reviewer, ať znovu přečte REVIEW_BRIEF.md a zkontroluje
aktuální kód mazání a čítače. Předchozí zjištění:
po smazání se čítač neaktualizoval.
Ať uvede, zda je problém odstraněný a na čem závěr stojí,
a také zkontroluje, zda oprava nenarušila nezávislost záznamů
se stejným názvem. Kód neměnit.

Teď hledáme odpověď na konkrétní otázku: je problém vyřešený a není narušené sousední chování, kterého se oprava mohla dotknout. Pro potvrzení chování na stránce zopakujte stejný scénář v prohlížeči. Pokud se opakované review dělalo jen nad kódem, toto omezení zůstává i v nové zprávě.

Zpráva může být kratší, delší, nebo nemusí obsahovat nová zjištění. V tom úspěch není. Důležité je, aby předchozí vada byla odstraněná, závěr vycházel z aktuálního kódu a nezkontrolované části zůstaly vidět. Rozhodli jste se opravu odložit? Pak si potvrzené zjištění a důvod odkladu uložte; opakovat review nezměněného kódu jen kvůli nové odpovědi nemá smysl.

6. Od zadání k ověřenému výsledku

Při práci s Claude Code pomáhá brief udržet vaše očekávání, zatímco hlavní agent předává úkol recenzentovi. Trvalý formát usnadňuje čtení odpovědi. Zapojit se ale stejně musíte, a to takto:

• hlavní agent sestaví zadání a předá ho vhodné roli; vy určujete očekávané chování a hranice;
• recenzent studuje soubory a vrací odůvodnění závěrů; a pokrytí a podstatná zjištění už kontrolujete vy;
• hlavní agent může zprávu upřesnit nebo na základě samostatného zadání opravit potvrzenou chybu; vy rozhodujete, co měnit a jak výsledek potvrdit.

U seznamu nákupů nebude výsledkem jen rada "přidej volání funkce", ale ověřené vysvětlení: při jaké akci číslo přestalo odpovídat, kde se aktualizace porušila a co se po opravě změnilo. S takovým výsledkem se už dá pracovat.