AI agent dělá pořád stejné chyby? Opravte systém, ne output

AI agent znovu nacpal byznys logiku do viewmodelu, smazal kód, který tam má být, a místo deseti řádků napsal padesát. Ruční oprava pomůže jen do příštího tasku. Rostislav Babáček, mobile team lead a vedoucí AI adopce v Ackee, prošel nejčastější chyby AI agenta, na které vývojáři v Claude Code narážejí, a ke každé ukazuje, kterou část systému opravit, aby se chyba už nevracela.

📋 TL;DR

• Opakovaná chyba AI agenta není smůla, ale chybějící znalost v systému. Opravený kód ji nepředá dál, opravené rules, glossary, ADR nebo workflow ano.
• Byznys logika ve viewmodelu zmizela, když se agent v .claude/rules naučil princip Tell, Don't Ask. Na vymyšlený naming pomohl glossary, na mazání „zbytečné“ logiky architektonická rozhodnutí (ADR).
• Když vývojáři nevědí, v jakém pořadí skilly pouštět, chybí orchestrační workflow. Jeden prompt spustí celý řetězec a nikoho nezdržuje, že commit skill běží dvě minuty.
• Nepochopené zadání řeší fáze interview-me, ve které agent zadání konfrontuje s codebase a doptává se. Odpovídá ale člověk a za špatnou odpověď agent nemůže.
• Ztráta disciplíny u velkého tasku je context rot. Pomáhá multi-phase plán, kde každá fáze běží v čistém kontextovém okně jako jedna vertical slice, takže aplikace jde po každé fázi zbuildit.
• Proti AI slopu běží po implementaci fáze deslop, proti ignorovaným pravidlům adversarial review dvou čistých subagentů nad git diff.
• Commit po každé fázi nahrazuje jeden nečitelný obří commit sérií spustitelných kroků.
• Hlavní pravidlo: neopravujte output, opravujte systém.

🩺 Diagnostika chyb AI agenta: symptom, příčina, oprava

Když Ackee od března 2026 nasazovalo agentní vývoj napříč 29 vývojáři a víc než patnácti codebases (od streamingové platformy přes bankovní aplikaci po logistiku s desítkami milionů balíků ročně), nevypadala realita jako příspěvky na LinkedInu, podle kterých AI jinde píše 90 % produkčního kódu. Vypadala jako seznam stížností. Agent nepochopil zadání. Ráno nepustil testy, odpoledne zapomněl na lint. Nechal v kódu hromadu zbytečných komentářů.

Babáček z těch stížností udělal pracovní metodu. Každá frustrace s agentem je informace, kterou agent nemá. Neví, že dělá něco špatně, a sám to nezjistí. Dá se ale zapsat do systému, ve kterém agent pracuje: do pravidel, projektového kontextu, workflow nebo review. Ruční oprava vyřeší jeden merge request, oprava systému všechny další.

Kvalitu outputu podle Babáčka formuje pět vrstev: model, built-in harness nástroje, project setup, zadání a schopnosti vývojáře. První dvě dostáváte s nástrojem a moc s nimi neuděláte. Zbylé tři má tým plně v rukou a právě v nich leží všechny opravy níže. Podrobně celý model popisuje článek Kvalita outputu AI agenta není samozřejmost, tady jde o praktický přehled symptomů.

🧩 Agent nerespektuje architekturu ani projekt

První tři symptomy mají společné to, že agentovi chybí znalost o projektu. Řeší je project setup, tedy CLAUDE.md, .claude/rules a projektový kontext.

Byznys logika skončila ve viewmodelu

Tým agentovi opakovaně psal, ať byznys logiku do viewmodelu nedává. Nepomáhalo to. Pomohl až kolega, který znal princip Tell, Don't Ask od Martina Fowlera. Když princip funguje v klasickém vývoji, proč ho nenaučit agenta? Do .claude/rules přibylo pravidlo s ukázkou a problém zmizel.

Obecné poučení: zákaz („nedělej X“) funguje hůř než pojmenovaný princip s příkladem. Agent pak ví, co dělat místo toho.

Agent si vymýšlí názvy tříd

Na jednom projektu agent nedodržoval zavedený naming a vymýšlel názvy, které v kontextu aplikace nedávaly smysl. Opravou byl glossary, tedy slovník pojmů v projektovém kontextu. Každý pojem v něm má tři části:

• hlavní, preferovaný název,
• popis,
• alternativní názvy.

Když agent narazí na alternativní název, glossary ho navede na primární a ten pak používá i v názvech tříd.

Agent maže logiku, kterou považuje za zbytečnou

Tenhle souboj vedl Babáček sám. Aplikace obsahovala logiku kvůli speciální metrice, kterou chtělo BI. Agent ji opakovaně označoval za chybu a mazal ji. Přesvědčit se ho nedařilo.

Do projektu proto přibylo architektonické rozhodnutí (ADR). Když si agent na začátku práce načítá kontext k souboru, najde i relevantní ADR a zjistí, že logika má svůj účel. Od té doby ji nechává být.

🔁 Agent nedodržuje proces: od skillů k workflows

Ackee má vývoj feature rozdělený do tří fází: analytické, implementační a finalizační (review na GitLabu). Každá fáze je posloupnost skillů. A s tím přišly nové stížnosti.

Nikdo neví, v jakém pořadí skilly pouštět

Vývojáři se ptali, v jakém pořadí skilly spouštět, jestli se něco stane, když jeden vynechají, nebo jestli ho můžou přesunout jinam. Pořadí přitom má svůj důvod. Řešením je workflow: plugin s orchestračním skillem, který spouští jednotky až desítky dalších skillů ve správném pořadí. Agent pak drží disciplínu sám a nikoho není potřeba učit, co následuje po čem. A stačí jeden prompt místo pěti.

„Commit skill trvá dvě minuty, udělám to ručně“

Ruční commit zabere zhruba 20 sekund, commit skill dvě minuty. Dokud vývojář pouští skilly ručně a čeká na ně, je ta stížnost oprávněná. Jakmile commit skill běží uvnitř autonomního workflow, přestanou dvě minuty navíc vadit. Vývojář na ně nečeká.

Stejný skill vzniká na dvou projektech

Na jednom projektu tým napsal build & test skill, na druhém kolegové napsali skoro stejný. Zbytečná práce. Ackee proto sdružuje pluginy do marketplaces ve třech vrstvách: sdílený pro všechny vývojové týmy, platformní (backend, frontend, mobil) a projektový. Skilly nejsou zkopírované v repozitářích, ale verzované jako jakákoli jiná závislost. Jak sdílení know-how přes pluginy funguje v praxi, popisuje článek Od promptů ke kolektivnímu know-how.

Agent zapomíná na testy a lint

Instrukce „spusť testy, build a lint“ byla v CLAUDE.md. Jenže CLAUDE.md je doporučení, ne vynucení. Agent ho někdy dodržel, jindy ne. Spolehlivou opravou je krok verify přímo v implementační smyčce: aplikace se zbuildí, otestuje a zlintuje, nálezy se vrátí agentovi, ten je zapracuje a celý krok jede znovu. Dokud neprojde, fáze není hotová.

🔍 Agent nepochopil zadání

Analytická fáze je podle Babáčka ta nejdůležitější. Začíná tím, že agent dostane odkaz na tiket a sám si stáhne obsah z Redmine, Azure DevOps nebo Jiry. Cílem je zadání, podle kterého by task bez chyb implementoval i člověk, který projekt nikdy neviděl. K agentovi je potřeba přistupovat jako ke kolegovi, kterému chybí kontext, a ten kontext mu dodat.

Implementoval něco úplně jiného

Agent si zadání sestavil, pustil se do práce a výsledek byl úplně mimo. Do analytického workflow proto přibyla fáze interview-me. Agent si nastuduje zadání, udělá hluboký průzkum codebase a začne navrhované řešení konfrontovat s tím, co v kódu skutečně je. Hledá díry v zadání a doptává se.

Tahle fáze je z velké části human in the loop. Agent se ptá na věci, které mu nejsou jasné, a odpovídá vývojář. Když odpoví špatně, definuje špatné zadání. Pak se ale nemůže zlobit na agenta, že implementace nesedí.

Klient používá pro jednu věc několik názvů

Zadání od klienta občas označuje tutéž věc třemi různými pojmy. Agent pak neví, o co jde, a dělá chyby. Oprava: v analytické fázi se načítá a aktualizuje projektový kontext. Kromě glossary a ADR v něm je aktuální API specifikace (tým ji obnovuje každý sprint), databázové schéma nebo odkazy do Figmy.

🍰 Agent ztrácí disciplínu u velkých tasků

Po chvíli implementace dělá něco jiného

Agent dostal zadání, vytvořil si plán a začal implementovat velkou funkcionalitu v jediném kontextovém okně. Narazil na jeho limity, nastoupil context rot a občas i compaction, která je ztrátová. Informace se cestou ztrácejí.

Opravou je skill, který vytváří multi-phase plán. Velký problém se rozseká na podproblémy a každý se řeší v samostatném, čistém kontextovém okně. Agent se k limitům okna nedostane a výstupy jsou kvalitnější.

Po fázi nejde aplikace ani zbuildit

Babáček implementoval funkcionalitu, u které potřeboval po třech fázích z pěti otestovat databázovou migraci. Nechal agenta po třetí fázi zastavit, ale aplikace nešla zbuildit. Agent si totiž vícevrstvou architekturu rozdělil po vrstvách: v prvních fázích změnil jen repository, ale ne vrstvy, které na ní visí.

Opravou jsou vertical slices, známé jako tracer bullets z knihy The Pragmatic Programmer. Každá fáze plánu prochází všemi dotčenými vrstvami najednou, jen v tenkém řezu. V první fázi třeba vznikne tlačítko a celá cesta k datům, jen místo zápisu do databáze se zatím vypíše do logu „ahoj“. Každá fáze jde zbuildit a otestovat.

⚙️ Kód funguje, ale nelíbí se vám

Implementační fáze v Ackee běží jako smyčka nad jednotlivými fázemi plánu: TDD, deslop, adversarial review, verify, commit. Většinou AFK, tedy bez člověka u klávesnice. Člověk zasahuje jen tehdy, když je to potřeba.

Agent to udělal na jeden zátah

Plán měl deset fází. Agent je implementoval postupně, ale odevzdal v jednom obřím commitu. Výsledkem byla one-shot implementace, ve které se nedalo vyznat, a když bylo potřeba něco odladit, nezbývalo než všechno revertnout.

Oprava: commit po každé fázi plánu, obohacený o kontext. V kombinaci s vertical slices je každý commit spustitelná aplikace. Dá se mezi nimi proklikat, sledovat, jak agent postupoval, a ladit konkrétní krok.

Zbytečné komentáře a padesát řádků místo deseti

TDD má fázi red-green-refactor s pokynem k minimální implementaci, a přesto ji agent nedodržoval. Do smyčky proto přibyla fáze deslop zaměřená na typické symptomy AI slopu. Projde nově vygenerovaný kód, odebere zbytečné komentáře, vyřeší zbytečné zanořování a pustí simplify, který implementaci zjednoduší.

Pravidla existují, ale agent je ignoruje

Ani .claude/rules nejsou zárukou. Ve velkém kontextu agent některé věci odsune stranou a prioritizuje si, co sám uzná za vhodné. Proto smyčka obsahuje adversarial review pomocí dvou čistých subagentů. Nevědí, proč se kód napsal tak, jak se napsal, takže nemají bias implementátora. Dostanou jen git diff. První subagent ho validuje proti .claude/rules, druhý proti fázi plánu, tedy proti zadání.

Od zavedení téhle kontroly už Babáček podle svých slov na merge requestu neviděl kód, který by porušoval definovaná pravidla. Celá smyčka běží na pozadí a do implementace tým zhruba v 95 % případů nesahá. Uvolněný čas jde do analytické a verifikační fáze, kde je člověk opravdu potřeba.

🎓 Když problém není v agentovi, ale v týmu

Část stížností nemířila na agenta, ale na to, jak s ním tým pracuje.

• „Proč mi ten setup nefunguje v Cursoru?“ Když každý používá jiný nástroj, setup projektu se tříští. Ackee proto zvolilo jednotnou platformu, Claude, mimo jiné kvůli přesahu do back office a dalších týmů.
• „Používám --dangerously-skip-permissions, vadí to?“ a „Nahradím lint script skillem.“ Deterministický linter nemá smysl měnit za skill a obejití permission systému není drobnost. Na tyhle otázky v Ackee odpovídá vzdělávací framework pro vývojáře o dvanácti úrovních. Začíná od úplných základů (permission systém, sandboxing, dev container, progressive disclosure u skillů, proč nemít zapnutých 50 MCP serverů) a tým jím prochází společně, aby nikdo neutekl daleko dopředu a zbytek nezůstal pozadu. Jak fungují oprávnění v Claude Code, rozebírá článek Claude Code permissions: kdo rozhoduje, co AI agent smí.
• Převzatá sada skillů je černá skříňka. Hotové sady jako superpowers jsou podle Babáčka stovky řádků textu, u kterých nevíte, proč tam který pattern je. Vlastní skilly napasované na konkrétní use casy vystačí s desítkami řádků, fungují spolehlivěji a spotřebují méně tokenů.

🔧 Neopravujte output, opravujte systém

Nejčastější chyba nevzniká v agentovi, ale na merge requestu. Reviewer napíše, že řádek je potřeba zalomit, autor to opraví ručně a jde dál. Do .claude/rules ale nic nepřibude, a tak se stejná připomínka objeví na dalším merge requestu, a pak znovu.

K tomu patří, že si harness musí tým stavět sám a být u toho. Kdo neví, co v systému je a proč, nebude mu věřit. A bez času na vzdělávání to nejde. Vývojáři, kteří harness neznají, na něj hlavně nadávají. Když pochopí, proč tam jednotlivé kroky jsou, začnou ho sami rozšiřovat.

🎯 Co si odnést

• Každá opakovaná chyba agenta je znalost, která v systému chybí. Zapište ji tam, kam patří: do rules, glossary, ADR, workflow nebo review.
• Pojmenovaný princip s příkladem funguje lépe než zákaz.
• Co musí proběhnout vždy, nepatří do CLAUDE.md, ale do workflow s feedback loopem.
• Velké tasky dělte na fáze ve vertical slices, každou v čistém kontextu a s vlastním commitem.
• Kdo opraví output a ne systém, opravuje stejnou chybu znovu. A kdo nesdílí, brzdí i sebe.

Podobné postřehy z Ackee najdete v newsletteru – přihlaste se a příští takový obsah vám přijde přímo do schránky.