Dluh v porozumění kódu: jak ho ustát, když kód píše AI agent

Kontrolu nad kódem od AI agenta si udržíte tak, že zadání, definici důkazu a konečné schválení necháte u člověka. Agentovi svěříte jen práci uvnitř smyčky. Postup: vlastní hypotéza, malé kroky, testy schvalované zvlášť a review zaměřené na to, co testy nedokazují. Jinak roste dluh v porozumění kódu.

Co je dluh v porozumění kódu a jak vzniká?

Dluh v porozumění vzniká, když tým přijímá kód rychleji, než stihne pochopit rozhodnutí, předpoklady a důsledky, které v něm agent zanechal.

Pojem razil Jeremy Twei. Addy Osmani ho rozpracoval pro kód psaný agenty. Podle něj agent vytváří a mění kód rychle, ale člověk nestíhá průběžně chápat, proč je napsaný právě takto. Příbuzný jev v týmech popisuje Margaret-Anne Storey jako kognitivní dluh. Tým postupně ztrácí sdílenou teorii systému, tedy společnou představu o tom, jak a proč systém funguje.

Zrádné je, že v okamžiku vzniku tento dluh nikdo nevidí. Kódová báze vypadá čistě, testy procházejí a build je zelený. Problém se ukáže až při další změně, kdy tým zjistí, že systému nikdo nerozumí. Osmani zároveň upozorňuje, že tento dluh jde splácet. Úplný mentální model velké kódové báze nedrží v hlavě nikdo. Stačí umět ho lokálně obnovit a vědět, co vám chybí.

Od delegování ke kognitivní kapitulaci

Delegovat práci na agenta je v pořádku. Problém nastává, když s úkolem nevědomky předáte i úsudek. Osmani popisuje tři stavy jako spektrum. Pojem kognitivní kapitulace (cognitive surrender) převzal od Stevena Shawa a Gideona Naveho z Whartonu.

Rozlišení tří stavů popisuje Addy Osmani, který na ně navazuje i v textu o dluhu v porozumění.

Posun dolů po spektru je pozvolný a každý jeho krok působí rozumně. Poslední odpověď byla dobrá, takže další jen přelétnete. U třetí už sledujete jen kostru. Pak se vás někdo zeptá na konkrétní řádek a vy ho nedokážete vysvětlit ani s pomocí agenta. Osmani doporučuje jednoduché pravidlo: kde je omyl levný, delegujte celé. Kde nesou následky jiní, tedy u rozhodnutí, co stavět, co ovlivní uživatele a zda je bezpečné nasadit, si úvahu nechte u sebe.

Test vlastnictví: umíte to vysvětlit?

Ano, pokud dokážete vysvětlit, co změna dělá a proč, třeba i s pomocí agenta. Když to nedokážete, vlastnictví jste ztratili. Praktický příklad, jak ověřovat výstupy více agentů, ukazuje náš popis toho, jak postavit tým agentů v Claude Code.

Paradox dohledu a atrofie dovedností

Čím rychleji agent generuje změny, tím víc by měl člověk kontrolovat. Stejná rychlost ale zvětšuje objem výstupu nad kapacitu review. Osmani tomu říká orchestration tax. Je to rozdíl mezi tím, co agenti vyprodukují, a tím, pod co jste ochotni se podepsat.

Druhé riziko je pomalejší: přestanete trénovat dovednosti, které jste dřív používali denně. Riziko atrofie dovedností řeší i novější preprinty na arXivu (2605.01160, 2607.06101). Jejich závěry zatím nejsou ustáleným konsenzem. Doporučujeme položit si Osmaniho otázku: co už necvičím? Část rutinního ladění klidně pusťte, ale vědomě.

Proč nestačí, že testy prošly

Zelená značka dokládá jednu vlastnost, ne správnost celku. Pokud test vznikl se stejnou chybou jako funkce, projde. Agenti navíc psaní testů tak zlevnili, že zelené značky přibývají rychleji, než roste jejich výpovědní hodnota.

Osmani upozorňuje na horší scénář. Agent může změnit implementaci a zároveň přepsat stovky testů, aby odpovídaly novému chování. Prošlé testy pak dokazují jen konzistenci kódu s upravenými testy, ne původní záměr. Úzkým hrdlem proto už není psaní kódu, ale jistota, že je správně.

Empirická data tento vzorec potvrzují. Studie publikovaná v ACM vychází z rozhovorů se zkušenými vývojáři. Popisuje čtyři formy dohledu nad agenty: kontrolu předem, společné plánování, monitorování v reálném čase a následnou kontrolu. Zároveň zjistila, že vývojáři berou výsledky testů jako záruku správnosti, i když testy mohou stát na stejných chybných předpokladech jako implementace.

Údaj 50 % proti 67 %, který Osmani cituje, je třeba číst opatrně. Pochází ze sekundárních zdrojů a plná metodika studie, včetně velikosti vzorku, není z citací zřejmá. Jde o rozdíl 17 procentních bodů podle stejného textu, ne o relativní pokles. Bereme ho jako signál, ne jako změřený zákon.

Jak nastavit verifikační smyčku pro AI agenta

Verifikační smyčka funguje, když člověk předem určí, co znamená „ověřeno“, a agent nesmí být jediným zdrojem implementace i důkazu. Podle dokumentace Claude Code agent opakovaně prochází fázemi získání kontextu, provedení akce a ověření výsledků. Osmani cituje Borise Chernyho z týmu Claude Code: dejte agentovi způsob, jak ověřit vlastní práci. Místo čtení každého řádku pak stavíte smyčky a posuzujete důkazy.

Postup krok za krokem

Krok 4 jde vynutit i technicky. Následující git hook odmítne commit, který současně mění implementaci i testy. Agent tak musí změnu testů předložit odděleně, kde ji člověk vidí.

#!/usr/bin/env bash
# .git/hooks/pre-commit – testy a implementace nesmí být v jednom commitu,
# aby změna očekávání nezapadla v diffu implementace
staged=$(git diff --cached --name-only)
tests=$(echo "$staged" | grep -E '(^tests/|\.(test|spec)\.ts$)' || true)
impl=$(echo "$staged" | grep -E '^src/' | grep -vE '\.(test|spec)\.ts$' || true)

if [[ -n "$tests" && -n "$impl" ]]; then
  echo "Změny testů dejte do samostatného commitu se zdůvodněním."
  echo "Dotčené testy:"
  echo "$tests"
  exit 1
fi

Co hlídat u zadání

Kvalita zadání odráží, jak dobře problému rozumíte. Kolega by vágní požadavek zpochybnil. Agent mezery doplní sám a vrátí něco, co vypadá hotově. Do zadání proto patří rozsah souborů, věci mimo rozsah, invarianty, které se nesmí změnit, příkazy pro ověření a podmínka, kdy se má agent zastavit. Typicky jde o změnu veřejného API, databázového schématu nebo oprávnění.

Pozor i na řetězení agentů. Každý další agent snadno dostane jen shrnutí od předchozího a originál nikdo nečte. Kdy dává smysl jeden agent a kdy více specializovaných, rozebíráme v článku o tom, jak volit mezi přístupy single agent loop a subagenti.

Jak dluh v porozumění v týmu měřit a omezovat

Standardní metrika pro dluh v porozumění neexistuje. Týmy proto kombinují nepřímé ukazatele technické kvality a schopnosti lidí změnu vysvětlit. Jednotlivě nic nedokazují, ale jejich trend ukáže, kde porozumění mizí.

Přehled ukazatelů, které doporučujeme sledovat, a signálů, na které reagovat:

• Doba do smysluplného review: sledujte čas skutečné kontroly, ne kliknutí na Approve. Varovný signál jsou velké diffy schválené během minut.
• Změny testů spolu s implementací: sledujte podíl pull requestů, kde se mění obojí. Varuje, když se testy mění pokaždé, kdy selžou.
• Mutation score: ukazuje, kolik vnesených chyb testy zachytí. Varuje vysoké pokrytí při nízkém skóre.
• Vysvětlitelnost změny: vzorkujte pull requesty a ptejte se, zda jiný vývojář po 24 hodinách popíše účel změny. Varují odpovědi typu „to dělal agent“.
• Rekonstrukce mentálního modelu: měřte, jak dlouho nováček hledá modul a invarianty. Varuje doba, která roste, i když je CI zelené.

Principem je to, co zdůrazňuje Osmani: testy ověří jen předem zakódované předpoklady, ne správnost zvoleného chování.

Druhou páteří jsou záznamy architektonických rozhodnutí (ADR) uložené v repozitáři, ne v konverzaci s agentem. Konverzace skončí, ADR zůstane a další člověk i další agent z něj obnoví důvody. Do pull requestu pak doporučujeme přidat krátkou šablonu.

Kdy plná autonomie nestojí za to a kdo ručí

Autonomii agenta stupňujte podle síly nezávislého ověření. Kde chybí silné testy, kontrakty nebo ruční scénáře, plná autonomie jen odkládá problém do produkce. Opakují se tři chyby. První je rubber stamping, tedy formální schválení bez porozumění. Druhou je agent, který přizpůsobuje testy své implementaci. Třetí je schválení podle struktury diffu místo podle rozhodnutí, která agent udělal.

Osmani nabízí test, který používáme i my: vsadili bychom na tuto změnu před člověkem, který ji bude udržovat? Pokud ne, nejde o review, ale o naději. Řešením je zpřísnit kontroly, aby člověka potřebovalo méně změn, nebo zpomalit. Další paralelní session nepomůže.

V nobig.deals nasazujeme agenty tak, že vnější smyčka zůstává u člověka. Člověk stanoví cíl, určí důkazy a schválí výsledek. Jak k tomu přistupujeme v praxi, popisujeme v rámci služby AI agenti a automatizace. Týmům, které chtějí tento režim zavést do celého vývojového procesu, nabízíme AI transformaci pro vývojáře. Ať agenti ve vývoji softwaru převezmou jakoukoli část práce, odpovědnost za kód v produkci nese vývojář, který změnu pustil dál.

Časté otázky

Co je comprehension debt a jak se liší od technického dluhu?

Comprehension debt je dluh v porozumění: tým provozuje kód, kterému už dostatečně nerozumí. Technický dluh se týká kvality kódu, třeba zkratek nebo zastaralé architektury, a obvykle je vidět. Dluh v porozumění může vzniknout i v čistém kódu se zelenými testy. Projeví se až ve chvíli, kdy je potřeba systém změnit a nikdo neumí vysvětlit, proč funguje právě takto.

Stačí ke kontrole kódu od AI agenta zelené testy?

Nestačí. Kontrola kódu od AI agentů se nemůže opírat jen o zelený build, protože test může nést stejnou chybu jako implementace. Agent navíc dokáže testy přepsat tak, aby odpovídaly jeho řešení. Vždy se ptejte, co konkrétní test dokázal a co ne. Citlivost testů ověřte mutačním testováním a změny testů schvalujte odděleně od implementace.

Co je kognitivní kapitulace u vývojářů?

Kognitivní kapitulace je stav, kdy výstup AI tiše přijmete za svůj a necítíte potřebu ho kontrolovat. Pojem zavedli Steven Shaw a Gideon Nave z Whartonu. U vývojářů se projevuje postupně: nejdřív čtete pozorně, pak jen přelétáte a nakonec schvalujete podle struktury. Poznáte ji tak, že nedokážete vysvětlit řádek, který jste sami schválili.

Jak poznám, že agent upravil testy podle své implementace?

Nejspolehlivěji tak, že změny testů nikdy nepřijmete ve stejném commitu jako implementaci. Pak je každá změna očekávání vidět samostatně a vyžaduje zdůvodnění. Varovné signály jsou oslabené aserce, nově přeskočené testy a očekávané hodnoty přepsané na to, co kód právě vrací. Pomáhá také git hook nebo pravidlo v CI, které smíšené commity odmítne.

Musím číst každý řádek kódu od AI agenta?

Ne, ale musíte vlastnit vnější smyčku. Předem definujte, co znamená „ověřeno“, a nejdřív kontrolujte důkazy, tedy spuštěné příkazy a jejich výstupy. Od agenta si nechte vypsat rozhodnutí a předpoklady. U rizikových míst, jako jsou transakce, oprávnění nebo výchozí hodnoty, čtěte pozorně. Když nedokážete říct, co kontroly minuly, chtějte skutečné review místo rychlého schválení.