Proč AI systémy selhávají bez dobré dokumentace – a jak to napravit

AI systém bez dokumentace selhává, protože AI má k dispozici jen to, co jí napíšeš - žádnou intuici, žádný firemní kontext „který se ví". Dokumentace není poznámka na potom, je to mozek tvého agenta. Řešení se jmenuje kontextové inženýrství a začíná souborem jako CLAUDE.md.

Stavíš AI agenta. Konfiguruješ prompty, nastavuješ workflow, testuješ. A pak si řekneš: dokumentaci napíšu později. Tohle je nejčastější chyba, kterou u firem vidím. A platíš za ni dráž, než čekáš.

Proč AI potřebuje dokumentaci jinak než člověk?

Protože člověk má kontext, intuici a může se zeptat. Přečte si 80 % dokumentu a zbytek doplní ze zkušenosti. AI má výhradně text, který jí dáš.

AI neumí číst mezi řádky. Neumí „nějak poznat", co máš na mysli. Když to není v dokumentu, pro AI to neexistuje. Nový zaměstnanec se doptá kolegy u kávy. Agent ne - buď to má napsané, nebo si to domyslí (a to je přesně ta chvíle, kdy vznikají halucinace a chyby).

Přirovnání, co používám u klientů: AI agent bez dokumentace je jako nový člověk první den bez onboardingu. Šikovný, ale nemá tušení, jak to u vás chodí. A na rozdíl od člověka se nezlepší sám tím, že „nasaje atmosféru".

Co je kontextové inženýrství?

Kontextové inženýrství (context engineering) je disciplína, jak dostat do AI ve správnou chvíli právě ty informace, které potřebuje - a nic navíc. Anthropic ho označuje za dovednost, která odlišuje ty, co z AI agentů vytáhnou 10násobnou hodnotu, od těch, co dostanou jen dvojnásobek.

Není to jen „napsat dobrý prompt". Je to o tom, jak strukturuješ dokumentaci, co agentovi dáš do kontextu, co naopak schováš, a jak zabráníš tomu, aby se v tom utopil.

Co je context rot a proč víc textu škodí?

Context rot (rozklad kontextu) je jev, kdy kvalita odpovědí AI klesá s tím, jak roste množství textu, které dostane - i u jednoduchých úkolů. Zní to kontraintuitivně: člověk by čekal, že víc informací = lepší odpověď. U AI je to naopak.

Studie Context Rot od firmy Chromy je tvrdý důkaz. Otestovala 18 nejsilnějších modelů (včetně GPT-4.1, Clauda a Gemini) a všechny do jednoho zhoršovaly výkon s rostoucí délkou vstupu. Některé modely držely přesnost kolem 95 % a pak po překročení určité délky spadly na 60 %. A to nepredikovatelně - u každého modelu jinde.

Praktický dopad: nacpat agentovi „pro jistotu" celou firemní wiki o 200 stránkách není pomoc, je to sabotáž. Čím víc balastu, tím větší šance, že přehlédne to podstatné. Dokumentace pro AI musí být hutná a přesná, ne obsáhlá.

Co je CLAUDE.md a proč je to nejdůležitější soubor?

CLAUDE.md je soubor, který si Claude (AI asistent od Anthropicu) automaticky načte na začátku práce - jsou v něm pravidla, kontext a preference, jak má v daném projektu fungovat. Je to nejdůležitější artefakt kontextového inženýrství, protože definuje „ústavu" agenta.

Co do něj patří:

Kdo agent je a jakou roli hraje
Tvrdá pravidla - co nikdy nesmí udělat (třeba nikdy nemazat data bez potvrzení)
Struktura projektu - kde co leží, kam co ukládat
Konvence - jazyk, styl, formát výstupů
Napojené systémy - jaké nástroje má k dispozici a jak je používat

Klíč je stručnost. CLAUDE.md se načítá pokaždé, takže každý zbytečný odstavec ubírá místo na to podstatné. Píšeš ho jako pravidla, ne jako esej.

Jak napsat dokumentaci, kterou AI fakt použije?

Pár konkrétních principů, co v praxi fungují proti context rotu a chybám:

Princip	Proč
Hutně, ne obsáhle	Míň textu = menší context rot
Explicitní pravidla	AI nečte mezi řádky
Načítat až když je potřeba	Detaily do vedlejších souborů, ne do hlavního kontextu
Příklady dobrého i špatného	AI se učí ze vzorů líp než z abstraktních pravidel
Průběžně aktualizovat	Zastaralá dokumentace je horší než žádná

K tomu pomáhají dvě techniky, co používají zkušené týmy. Kompakce - když se konverzace blíží limitu, shrne se do hutného výtahu a pokračuje se z něj, aby výkon nespadl. A izolace do subagentů - průzkumnou práci odděl do samostatného agenta s vlastním kontextem, ať hlavní agent nevidí celý proces hledání, jen výsledek.

Jak vypadá selhání kvůli špatné dokumentaci v praxi?

Konkrétní příklad, který vidím pořád dokola. Firma nasadí AI agenta na zákaznickou podporu. Funguje fajn na jednoduché dotazy, ale u složitějších začne vymýšlet - slíbí slevu, co neexistuje, nebo pošle klienta na oddělení, které firma nemá.

Proč? Protože v dokumentaci nikdo nenapsal, co agent NESMÍ. Chyběla tvrdá pravidla. Agent dostal svobodu tam, kde měl mít mantinely. Oprava nebyla „lepší model", ale tři odstavce jasných zákazů v dokumentaci. Náklady na tenhle omyl? Naštvaní zákazníci a den práce navíc, který se dal ušetřit hodinou psaní předem.

Druhý typický scénář: agent má přístup k datům, ale dokumentace neříká, která jsou aktuální. Tak si vezme starou verzi ceníku a začne fakturovat podle loňských cen. Zase - ne chyba modelu, ale chybějící kontext.

Co to znamená pro české firmy?

Většina českých firem, co u mě řeší AI, má stejný problém: znalost žije v hlavách lidí, ne v dokumentech. „To se ví, jak to děláme." Jenže AI to neví. A dokud to nikdo nenapíše, žádný agent to nebude umět.

Dobrá zpráva: sepsání téhle znalosti se vyplatí i mimo AI. Onboarding nových lidí, zastupitelnost, konzistence procesů - to všechno těží z toho samého dokumentu. AI je vlastně jen důvod, proč to konečně uděláš.

Ekonomika je jasná. Den práce na pořádné dokumentaci (v přepočtu klidně 8 000-12 000 Kč času specialisty) ti ušetří týdny ladění agenta, který pořád dělá věci špatně, protože neví jak. Levnější je napsat to jednou pořádně než donekonečna opravovat výstupy.

Kdy dokumentace nestačí?

Dokumentace není všelék. Nevyřeší dvě věci:

Halucinace - i s perfektní dokumentací si model občas vymyslí. Pořád potřebuješ ověřovací vrstvu a u kritických rozhodnutí člověka.
Špatně navržený proces - když je samotný workflow chaotický, dokumentace ho jen popíše. AI ti nezachrání blbý postup, jen ho zrychlí.

Shrnutí: AI agent je jen tak dobrý, jak dobrý je jeho kontext. Dokumentaci nepiš na potom - piš ji jako první, protože je to doslova mozek celého systému. A drž ji hutnou, aby ses nechytil do context rotu.