Coding agenti bez halucinací: kratší instrukce, grounding a kontrola výsledku

Coding agent nezačne „halucinovat“ jen proto, že je model slabý. Často mu sami vytvoříme prostředí, ve kterém má příliš mnoho starého kontextu, rozporná pravidla, nejasný zdroj pravdy a žádnou povinnost výsledek ověřit.

Praktický důsledek je nepříjemný: dlouhý AGENTS.md nebo CLAUDE.md nemusí být výhoda. Může zvýšit cenu každého kroku a přidat další šum, aniž by agent úkol dokončil častěji. Lepší pattern je menší sada trvalých instrukcí, kontext načítaný podle potřeby, grounding na skutečná data a kontrola hotového výsledku.

Dlouhé kontextové okno není spolehlivá paměť

Kontextové okno říká, kolik tokenů model technicky přijme. Neříká, že je všechny použije stejně dobře. Studie Lost in the Middle ukázala typický U-profil: modely využívaly informaci lépe na začátku nebo na konci kontextu a hůř uprostřed. Šlo o starší modely a konkrétní experimenty, takže z toho nelze dělat univerzální procento pro dnešní coding agenty. Provozní závěr ale zůstává užitečný: více kontextu automaticky neznamená přesnější výsledek.

U dlouhého agentního běhu se navíc hromadí plán, výstupy nástrojů, chyby, opravy a slepé uličky. Když se historie kompaktuje, vzniká ztrátové shrnutí. Claude Code po /compact znovu načte projektový CLAUDE.md, ale instrukce, které existovaly jen v konverzaci, se mohou ze shrnutí vytratit. Proto trvalé dohody nepatří jen do chatu.

`AGENTS.md` a `CLAUDE.md` jsou kontext, ne firewall

Codex před prací skládá instrukce z AGENTS.md souborů od kořene projektu směrem k aktuální složce. Claude Code používá CLAUDE.md; pokud chcete jednu sadu pravidel pro oba nástroje, může CLAUDE.md importovat @AGENTS.md.

Oba mechanismy jsou užitečné, ale nejsou tvrdé vynucení. Anthropic výslovně popisuje CLAUDE.md jako kontext, který řídí chování, nikoli jako bezpečnostní konfiguraci. Zákaz destruktivního příkazu proto patří do permissions, sandboxu nebo hooku. Do instrukčního souboru patří hlavně to, co má agent vědět a jak má pracovat.

Dobrá trvalá instrukce je například:

## Ověření změny

- Po změně fakturační logiky spusť integrační testy pro invoices.
- Za zdroj pravdy pro sazby DPH považuj `src/tax/rates.ts`.
- Pokud údaj nelze ověřit v repozitáři nebo dokumentaci, označ ho jako neověřený.

Slabší varianta je seznam desítek obecných zákazů typu „nedělej chyby“, „nevymýšlej si“ a „vždy piš kvalitní kód“. Agent z nich nepozná, kde hledat důkaz ani jak zjistit, že je hotovo.

Studie o `AGENTS.md`: méně jistoty, více nákladů

Preprint Evaluating AGENTS.md zkoumal repository-level context files u coding agentů na SWE-bench úlohách i v repozitářích s instrukcemi od vývojářů. Výsledek není argument pro zrušení AGENTS.md. Je to argument pro jeho údržbu.

Autoři zjistili, že context files obecně nezvyšovaly úspěšnost dokončení úloh a v průměru zvyšovaly inference cost o více než 20 %. Vývojářské instrukce v některých nastaveních mírně pomohly, ale automaticky generované soubory často vedly agenty k dalšímu průzkumu a vyšší spotřebě.

Důležitá přesnost: těch 20 % se vztahuje k průměrnému růstu nákladů, ne k univerzálnímu dvacetiprocentnímu poklesu kvality.

Proto bych /init nebo jiný generátor bral jako návrh k redakci, ne jako hotovou konfiguraci. Automatický soupis adresářů, závislostí a zřejmých příkazů agent často dokáže zjistit ze samotného projektu. V trvalém souboru mají větší cenu výjimky, skryté vazby, neobvyklé testovací kroky a důvody rozhodnutí.

Grounding: agent musí dostat cestu k důkazu

Grounding znamená, že odpověď nevzniká jen z pravděpodobného pokračování textu. Agent si má sáhnout na konkrétní zdroj pravdy.

V coding workflow to může být:

přečtení aktuální implementace a schématu databáze,
spuštění testu nebo typechecku,
otevření oficiální dokumentace k používanému API,
porovnání výsledku s logem, screenshotem nebo skutečnou HTTP odpovědí,
uvedení souboru, testu nebo odkazu, o který se tvrzení opírá.

Stejný princip funguje i mimo vývoj. Agent pro faktury má číst účetní pravidla a data objednávky, ne tipovat sazbu. Lead triage má používat pole z CRM a definovaná kritéria. Support classification má vrátit nejen štítek, ale i evidenci ze zprávy, která rozhodnutí odůvodňuje.

V n8n nebo Make bych oddělil tři kroky: načtení relevantních dat, rozhodnutí modelu a deterministickou validaci výstupu. Když model vrátí strukturovaný JSON, další node může zkontrolovat povinná pole, povolené hodnoty, datum, součty nebo existenci citovaného záznamu.

Osm pravidel pro spolehlivějšího coding agenta

Oddělte obecné znalosti od projektové reality. Verzi API, architekturu a firemní pravidla nechte agenta ověřit v aktuálních zdrojích.
Udržujte trvalé instrukce krátké. V souboru nechte jen informace, které agent běžně nezjistí sám.
Pište pravidla jako konkrétní akce. „Po změně spusť test X“ je lepší než „nikdy nerozbij testy“.
Automaticky generované instrukce zkraťte. /init je dobrý začátek, ne hotová pravda.
Kompaktujte v přirozeném bodě. Před zkrácením historie uložte rozhodnutí, otevřené body a důležité důkazy do projektu nebo task memory.
Vyžadujte grounding. Agent má číst soubor, databázi, log nebo oficiální dokumentaci a uvést, z čeho vycházel.
Dejte mu únikovou cestu. Když informaci nelze ověřit, správný výstup je „neověřeno“, ne sebevědomý odhad.
Ověřujte dokončený výsledek. Test, lint, render, HTTP kontrola nebo lidské schválení musí odpovídat riziku změny.

Co bych měřil ve firmě

Úspěšnost agenta neposuzujte podle hezkého vysvětlení. Pro každé workflow sledujte dokončený úkol, počet opakování, tokeny, cenu, dobu běhu, zásahy člověka a typy selhání.

U coding agenta přidejte, zda prošly cílené testy a zda diff neobsahuje změny mimo zadání. U extrakce dokumentů měřte přesnost proti kontrolnímu vzorku. U CRM enrichmentu kontrolujte zdroj a stáří údaje. U supportu sledujte chybné eskalace, ne jen procento vyplněných štítků.

Teprve A/B test ukáže, zda nový AGENTS.md pomáhá. Vezměte například 30 reálných úloh, pusťte je se stávajícími instrukcemi a s kratší verzí a porovnejte úspěšnost i cenu. Pokud agent stejně úspěšně pracuje s polovičním souborem, odstranili jste kontextovou daň bez ztráty kvality.

Můj závěr

Nejspolehlivější agent není ten, kterému pošlete nejvíc textu. Je to ten, který dostane krátké trvalé instrukce, umí si načíst aktuální fakta, může přiznat nejistotu a musí výsledek ověřit.

AGENTS.md a CLAUDE.md mají velkou hodnotu jako mapa neobvyklých pravidel projektu. Jakmile se z nich stane automaticky generovaná encyklopedie repozitáře, platíte za další tokeny a přidáváte šum. Pro firmy je proto údržba agentního kontextu stejná provozní disciplína jako testy, logování nebo permissions.

Zdroje: Jirka Herník: Halucinuje vám AI? Mě ne!, OpenAI Docs: Custom instructions with AGENTS.md, Claude Code Docs: How Claude remembers your project, Gloaguen et al.: Evaluating AGENTS.md a Liu et al.: Lost in the Middle.