Každý vývojář to zná: otevřeš pull request a první, co vidíš, je odstavec textu, který napsal kolega — nebo ještě hůř, AI agent. „Refaktoroval jsem autentizaci, přidal testy, upravil konfiguraci." Co přesně se změnilo, proč, a co si máš jako reviewer opravdu projít, z toho nepoznáš. Musíš luštit diff po řádcích. Pull request review s AI nemusí vypadat takhle. Moderní workflow jde opačným směrem: agent místo textového shrnutí dodá tři artefakty — diagram změn, krátkou nahrávku a plán, podle kterého kód vznikl.
Tenhle návod ti ukáže, jak takový „self-explaining PR" nastavit v Claude Code pomocí dvou vlastních příkazů (/show-me a /merge-risk), Mermaid diagramů a video walkthrough. Výsledek: reviewer se neptá „co to má dělat", ale rovnou rozhoduje „schválit, nebo ne".
Proč textové shrnutí PR nestačí
Textové shrnutí má zásadní slabinu: píše ho ten, kdo kód vytvořil (nebo model, který ho napsal), a oba mají motivaci ho zkrátit. Typické AI shrnutí vypadá jako „přidána validace vstupů a opraveny edge casey" — věta, která zní dobře, ale reviewerovi neříká nic.
Mezitím roste objem kódu, který AI píše. Jak jsme popsali v článku o stacked PR na GitHubu, AI generuje kód rychleji, než ho tým stíhá kontrolovat — a GitHub sám doporučuje velké AI PRs rozdělovat do stacků (inženýrský blog GitHubu, 2026). Když review zpomaluje celý pipeline, řešení není psát delší shrnutí, ale změnit formát.
Pozor Delší text nepomáhá. Reviewer čte popisek PR průměrně pár vteřin — čím delší, tím menší šance, že ho dočte. Artefakty fungují, protože je čte rychleji než text: diagram zběhem pohledu, video při 1,5násobné rychlosti, plán jako checklist.
Tři artefakty místo jednoho odstavce
Self-explaining PR stojí na třech pilířích, z nichž každý pokrývá jinou otázku reviewera:
- Diagram odpovídá na „co se změnilo v architektuře". Mermaid diagram se v popisku PR na GitHubu renderuje nativně (GitHub changelog, únor 2022) — žádný obrázek nemusíš generovat ani nahrávat.
- Nahrávka odpovídá na „jak to funguje". Dvouminutové video walkthrough, kde agent projde diff a ukáže, co se děje v běžící aplikaci, nahradí půl hodiny klikání po souborech. Existují hotové Claude Code skills, které z URL pull requestu vygenerují komentované MP4 video s titulky.
- Plán odpovídá na „proč to vzniklo takhle". Export z plan módu (nebo ze zadání, podle kterého agent pracoval) ukáže záměr — reviewer tak kontroluje soulad plánu a výsledku, ne jen výsledek.
K tomu přidej čtvrtý, nepovinný prvek: důkaz ověření. Plugin show-me-the-work vynucuje, aby agent před prohlášením „hotovo" ukázal, že ověření (testy, lint, build) skutečně proběhlo — ne jen tvrdil, že proběhlo.
Jak nastavit workflow v Claude Code
Celé workflow drží pohromadě dva vlastní příkazy. Vlastní slash command v Claude Code je obyčejný Markdown soubor v .claude/commands/ — nic víc nepotřebuješ.
Krok 1: Vytvoř příkaz /merge-risk
Do .claude/commands/merge-risk.md napiš instrukci, která nechá agenta ohodnotit PR podle rizika, ne podle velikosti:
Projdi diff tohoto pull requestu a ohodnoť ho ve třech kategoriích:
1. Riziko merge (nízké/střední/vysoké) + jedna věta proč
2. Soubory, které si má reviewer projít osobně (max 3, s důvodem)
3. Co je pokryto testy a co ne
Odpověď vrať jako tabulku do komentáře PR. Nepiš obecnosti typu "zkontroluj edge casey".
Proč riziko a ne počet řádků? Protože 500 řádků přejmenování proměnných je bezpečnější než 15 řádků v payment flow. Jak celou pipeline poskládat end-to-end popisujeme v návodu AI code review pipeline, který ušetří týmu 5 hodin týdně — tady z ní zapojíš jen první filtr, který reviewerovi řekne, kam se dívat.
Krok 2: Vytvoř příkaz /show-me
Druhý soubor, .claude/commands/show-me.md, generuje samotné artefakty:
K tomuto pull requestu připrav tři věci a připoj je do popisku PR:
1. Mermaid diagram: jaké moduly diff mění a jak spolu po změně komunikují
(flowchart nebo sequence diagram, max 15 uzlů)
2. Plán: vyextrahuj zadání/plán, podle kterého kód vznikl, a označ,
které body plánu diff pokrývá a které ne
3. Seznam kroků k ověření: přesné příkazy, kterými reviewer změnu
ověří lokálně (test command, build, curl příklad)
Mermaid vlož přímo do markdownu PR, GitHub ho vykreslí sám.
Klíčová je poslední věta: Mermaid kód se vloží jako text do těla PR a GitHub ho na stránce vykreslí jako diagram. Reviewer vidí obrázek, ty držíš v repu jen text.
Krok 3: Připoj nahrávku tam, kde diagram nestačí
Diagram ukáže strukturu, ale ne dynamiku. U PRs, které mění UI nebo chování za běhu, přidej video walkthrough. Máš dvě cesty:
- Hotový skill (např. pr-walkthrough-video výše): předáš mu URL PR, on vrátí komentované MP4, které nahraješ jako přílohu do komentáře.
- Terminálová nahrávka přes asciinema: agent spustí testy a ukáže výstup; nahrávka je textová, malá a dá se přehrát přímo v prohlížeči.
Tip Video nedávej do každého PR. U změn pod ~50 řádků stačí diagram a plán — video si šetři pro PRs, kde se mění viditelné chování.
Krok 4: Zaveď pořadí: nejdřív /merge-risk, pak /show-me
Pořadí je důležité. Nejprv /merge-risk ohodnotí, jestli PR vůbec stojí za plné artefakty — u nízkého rizika (typo, copy změna, přejmenování) reviewer nepotřebuje video. U středního a vysokého rizika pustíš /show-me a PR se „vysvětlí sám".
Výsledný komentář v PR pak vypadá takhle:
## Riziko merge: STŘEDNÍ
Mění auth middleware — osobně projdi `src/auth/guard.ts`.
## Co se změnilo
(Mermaid diagram: login → guard → session store)
## Plán a pokrytí
✅ rate limiting přesunut do guardu · ✅ testy na 429 · ❌ audit log (chybí)
## Ověření
`npm test -- auth` · `curl -X POST localhost:3000/login -d '...'`
Reviewer vidí riziko, strukturu, záměr i způsob ověření na jedné obrazovce — bez luštění diffu.
Jak to vypadá v praxi týmu
Představ si typický týden. Agent v Claude Code napíše refaktor fakturačního modulu — 12 souborů, 800 řádků. Dřív bys jako reviewer strávil hodinu v diffu a stejně ses ptál na Slacku „proč je tady ten fallback".
Se self-explaining workflow otevřeš PR a vidíš: střední riziko, jeden soubor k osobní kontrole, diagram ukazující, že se fakturace nově ptá cenového service místo přímého dotazu do DB, plán s jedním nepokrytým bodem (zaokrouhlování cizích měn) a dvouminutové video, jak prochází testovací faktura. Review z hodiny zkrátíš na deset minut a rozhodnutí je informované — podobný princip „AI navrhuje, člověk rozhoduje" řešíme i v návodu na nastavení Copilot review.
A když PR přistane rovnou v CI, může na něj naskočit i multi-agent review — Anthropic v březnu 2026 představil systém paralelních agentů pro code review (detekce bugů, bezpečnosti, kvality a výkonu najednou), který komentáře řadí podle závažnosti. Tvůj /merge-risk pak slouží jako lidská kontrolní vrstva nad ním. Srovnání dedikovaných nástrojů (Greptile, CodeRabbit, BugBot) najdeš v recenzi AI code review nástrojů.
Jak workflow zavést v týmu za týden
Nenasazuj všechno najednou — tým by to odmítl jako další povinnou byrokracii. Postupuj po dnech:
- Pondělí: commitni
.claude/commands/merge-risk.mda pusť ho na vlastní PR. Ukaž týmu výstup na reálném příkladu. - Středa: přidej
/show-mes Mermaid diagramem. Domluv pravidlo: diagram povinný od 200 řádků diffu. - Pátek: jedno video walkthrough na největším PR týdne. Změř, kolik otázek „co to má dělat" zmizelo z review komentářů.
- Příští týden: zaveď pořadí risk-first do review checklistu. Když se osvědčí, přesuň oba příkazy do CI jako headless job.
Kde jsou limity
- Důvěra v artefakty. Diagram kreslí ten samý model, který psal kód — může zkreslit záměr. Proto vždycky nech v
/merge-riskaspoň jeden soubor k osobní kontrole. - Video zlobí u dynamických UI. Když se UI mění podle dat, nahrávka stárne rychleji než kód. U dlouho žijících větví video radši přegeneruj.
- Plán musí existovat. Když agent psal kód bez plánu (ad-hoc prompt), nemá
/show-meco extrahovat. Zvykni si agenta pouštět přes plan mód — plán je pak zdarma. - Velikost komentáře. Mermaid nad ~20 uzlů je nečitelný. Velké refaktory radši rozsekej na stacked PRs, jak ukazuje GitHub ve svém doporučení výše.
Časté otázky
Funguje to i mimo Claude Code?
Ano. /show-me a /merge-risk jsou jen Markdown soubory s instrukcemi — stejný princip přeneseš do Cursoru (rules), Copilota (custom instructions) nebo jakéhokoli agenta, který umí číst repozitář a psát do PR. Mermaid vykreslí GitHub, GitLab i Azure DevOps.
Kolik času workflow ušetří?
Závisí na velikosti PRs. U středních PRs (200–800 řádků) tým typicky zkrátí čas reviewera z 30–60 minut na 10–15, protože nemusí rekonstruovat záměr z diffu. U malých PRs nic nešetři — tam artefakty negeneruj vůbec.
Co když agent v diagramu lže?
Proto existuje /merge-risk: vždy označí aspoň jeden soubor k osobní kontrole, takže diagram slouží jako mapa, ne jako náhrada čtení. Plugin show-me-the-work navíc vynutí důkaz, že testy skutečně proběhly.
Musím video nahrávat ke každému PR?
Ne. Video dává smysl u změn viditelného chování (UI, API odpovědi, flow). U interních refaktorů stačí diagram a plán — jinak z tebe vznikne produkční studio místo týmu.
Jde workflow napojit na CI?
Ano. Oba příkazy umíš spustit headless (claude -p), takže je GitHub Actions zavolá po otevření PR a výstup zapíše jako komentář. Headless provoz bez dohledu řešíme v článku o nočních bězích Claude Code.
Závěr: PR jako produkt, ne jako poznámka
Textové shrnutí PR je relikt doby, kdy kód psal člověk a reviewer byl rád za pár vět navrch. Když kód píše agent, musí agent dodat i jeho vysvětlení — a formátem, který člověk zpracuje rychleji než odstavec textu. Diagram pro strukturu, nahrávka pro chování, plán pro záměr.
Začni jednoduše: vytvoř .claude/commands/merge-risk.md, pusť ho na příští PR a změř, kolik otázek „co to má dělat" ti v týmu zmizí. Pak přidej /show-me a Mermaid diagramy. Video nech na konec — je to třešnička, ne základ.
