Praktické tipy 22. 3. 2026

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

AI agent bez dokumentace je jako nový zaměstnanec bez onboardingu

Stavíš AI agenta. Konfiguruješ prompty, nastavuješ workflow, testuješ. Ale pak si řekneš – dokumentaci napíšu později.

Tohle je nejčastější chyba, kterou vidím. A platíš za ni dráž, než si myslíš.

Dokumentace pro AI systémy není to, co si pod tím většina lidí představí. Není to README soubor na GitHubu nebo firemní wiki plná zastaralých procesů. Je to doslova mozek tvého agenta. A pokud je špatná nebo chybí, agent selhává. Bez diskuse.

Klíčový rozdíl: dokumentace pro lidi vs. pro AI

Člověk má kontext, intuici, může se zeptat. Přečte si 80 % dokumentu a zbytek doplní z vlastní zkušenosti.

AI má pouze to, co dostane. Není tam intuice, není tam firemní kultura, „která se ví". Je tam výhradně text, který jí dáš.

AI neumí číst mezi řádky. Neumí „nějak poznat", co máš na mysli. Pokud to není v dokumentu, neexistuje to.

A to je zásadní rozdíl.

Jak AI čte a používá dokumentaci

AI jazykový model (LLM) pracuje s tím, co je v jeho context window – „okně kontextu". To je vše, co AI vidí v daném momentě: system prompt, dokumenty, historii konverzace, aktuální dotaz.

Dokumentace se do context window dostává třemi způsoby:

  1. System prompt – instrukce přímo vložené při inicializaci agenta. Tady je CLAUDE.md, pravidla, persona.
  2. RAG retrieval – dokumenty, které se dynamicky dohledávají na základě dotazu.
  3. Tool results – data, která agent získá vlastními akcemi (API, databáze, web).

Pokud v žádném z těchto zdrojů informace není, agent buď halucinuje, nebo řekne, že neví. Druhá možnost je lepší, ale ani jedna není ideální.

CLAUDE.md a podobné soubory – proč fungují

Jeden z nejefektivnějších přístupů k dokumentaci pro AI agenty je koncept CLAUDE.md – nebo jakýkoliv podobný „brain file".

Je to Markdown soubor, který přímo popisuje:

  • Kdo jsi a jaký máš byznys
  • Jaká jsou core rules – co se smí a nesmí
  • Jaký je workflow a systém práce
  • Jaké nástroje jsou k dispozici
  • Jaká jsou rozhodovací kritéria
  • Kontext byznysu a priorit

Tento soubor se vkládá jako system prompt. Agent ho má přímo před sebou na začátku každé session.

Výsledek? Agent nepředpokládá, nemusí domýšlet. Ví přesně, v jakém kontextu pracuje a čím se řídit.

Sám to používám – můj CLAUDE.md má přes 300 řádků a pokrývá vše od hard rules (nikdy nemaž soubory permanentně) po byznysový kontext a priority. Bez něj by můj AI Chief of Staff nevěděl, co dělá nebo proč.

Jak psát AI-friendly dokumentaci

1. Buď explicitní, ne implicitní

Nepředpokládej, že AI „ví". Pokud chceš, aby vedení mejlů probíhalo určitým stylem, napiš přímo jakým. „Profesionálně" je nevystihující. „Formální, bez emoji, s pozdravem jménem" je jasné.

2. Struktura > prose

Bullet pointy, nadpisy, sekce. AI lépe zpracovává strukturovanou dokumentaci než volný text. H2, H3, vnořené seznamy – toto je přítel AI.

3. Příklady, ne jen abstraktní pravidla

„Používej přátelský tón" je slabé. „Používej přátelský tón, příklad: ‚Ahoj, díky za zprávu! Mrknu na to dnes odpoledne.'" je silné.

4. Priority a váhy

Pokud má AI více pravidel, některá mohou být v konfliktu. Musíš říct, co má větší váhu. „Pokud instrukce kolidují, upřednostni X před Y."

5. Negativní instrukce

Nejen „dělej toto", ale i „nedělej tamto". „Nikdy neukonči konverzaci bez jasného dalšího kroku." „Nikdy neslibuj termíny bez ověření dostupnosti."

Jak udržovat dokumentaci aktuální

Dokumentace je živý dokument, ne jednorázová aktivita. Jak ji udržovat:

  • Integrace do workflow: Pokud se něco v byznysu změní, změň i dokumentaci. Přidej to do onboardingu pro každou velkou změnu.
  • Verze v gitu: Dokumentaci pro AI agenty spravuj jako kód. Git dává historii, možnost rollbacku, revize.
  • Feedback loop: Monitoruj, kde agent selhává nebo dělá chyby. Často je kořenová příčina chybějící nebo nesprávná dokumentace.
  • Regular audit: Každý měsíc nebo kvartál projdi dokumentaci a zkontroluj, co je zastaralé.

Nástroje pro AI dokumentaci

Co konkrétně používám a co doporučuji:

  • CLAUDE.md / system prompt soubory: Pro AI agenty postavené na Claude. Markdownový soubor přímo v projektu.
  • Context7: Nástroj, který dynamicky provádí lookup dokumentace pro kódové projekty. Skvělé pro vývojářské agenty.
  • Notion: Pokud máte velkou databázi firemních znalostí, Notion je dobrá základna pro RAG retrieval.
  • Markdown soubory v repozitáři: Pro code-centric workflow. Git verzované dokumenty jsou transparentní a snadno spravovatelné.

Dokumentace = mozek tvého AI systému

Pokud stavíš AI agenta nebo automatizaci a dokumentace je druhé místo na tvém seznamu priorit, této chyby se vyvaruj. Dokumentace je první místo.

Bez dobré dokumentace budeš ladit nesprávné věci. Budeš si říkat „AI nefunguje", když problém bude v tom, že AI nemá to, co potřebuje.

Investuj čas do dokumentace dříve než do optimalizace modelu. To je rada, která šetří měsíce frustrace.

Máš otázky k dokumentaci pro svůj AI projekt? Napiš mi – tohle je téma, o kterém mluvíme na všech workshopech, a rád sdílím konkrétní přístupy.

Zpět na blog