Na školeních často dostávám otázku, proč moje projekty nezačínají definicí CLAUDE.md. Primárně proto, že dlouhodobě mám zkušenost, že u postupně budovaného projektu není přínos tohoto souboru vygenerovaného automaticky z popisu projektu nijak zasadní. Teď to potvrzují i provedené studie. Pojďme se tedy podívat na příčiny i to, jak můžete své claude/agent soubory zlepšit. A pokud s Claude Code teprve začínáte, doporučuji nejdříve projít průvodce výukou Claude Code.
Kontextové soubory jako CLAUDE.md nebo AGENTS.md jsou v roce 2026 de facto standard pro agentní vývoj. Anthropic, OpenAI, Cursor i další doporučují vytvářet kontextové soubory pro repozitáře, aby AI agenti lépe chápali kódovou základnu. Vývojáři s tím tráví čas, firmy to přidávají do onboardingových procesů. Ale funguje to?
Výzkumníci z ETH Zurich a LogicStar.ai (Maran, Schluntz, Tschannen & Vechev, únor 2026) provedli první kontrolovaný experiment. Výsledky jsou spíše rozpačité. Zjednodušeně řečeno: soubory pomáhají spíše málo.
Co testovali
Autoři vzali 4 kódovací agenty — Claude Code (Sonnet 4.5), Codex (GPT-5.2), Codex (GPT-5.1 Mini) a Qwen Code (Qwen3-30B) — a testovali je na dvou benchmarcích:
SWE-bench Lite — 300 úloh z 11 populárních Python repozitářů (Django, Flask, Scikit-learn, Sympy…). Standardní benchmark pro opravy bugů. Agenti tyto repozitáře s vysokou pravděpodobností viděli v trénovacích datech.
AGENTBENCH — nový benchmark, který autoři vytvořili pro tuto studii. 138 úloh z 12 méně známých Python repozitářů s lidsky napsanými kontextovými soubory. Repozitáře byly vybrány záměrně tak, aby je agenti pravděpodobně neznali z trénování.
Každý agent řešil úlohy ve třech režimech:
- Bez kontextového souboru (baseline)
- S LLM-generovaným kontextovým souborem — vygenerovaným z kódu repozitáře pomocí Claude Code a Codex
- S lidsky napsaným kontextovým souborem — ručně připraveným autory studie
To dává solidní srovnání: stejná úloha, stejný agent, jediný rozdíl je přítomnost a typ kontextového souboru.
LLM-generované kontextové soubory výkon zhoršují
V 5 z 8 testovaných konfigurací (agent × benchmark) snížily LLM-generované soubory úspěšnost řešení. Průměrně o 0,5 % na SWE-bench Lite a o 2 % na AGENTBENCH. To není obrovský propad, ale rozhodně to není zlepšení.
Co je horší: náklady stoupají. Agenti s LLM-generovanými kontextovými soubory spotřebují o 20–23 % více kroků. A úměra je jasná. Více kroků = více tokenů = vyšší cena za každou vyřešenou úlohu. Platíte víc a dostáváte stejný nebo horší výsledek. Důvody jsou jednoduché - automaticky generované soubory nepřinášejí nic, co by agenti nezjistili jinak a naopak jsou dalším objemem do kontextu. Později se u toho na chvíli zastavíme.
Lidsky psané soubory pomáhají, ale mírně
Lidsky psané kontextové soubory přinášejí mírné zlepšení — v řádu jednotek procent, výraznější na AGENTBENCH (kde agenti repozitáře neznají) než na SWE-bench Lite. Není to dramatický skok. A i lidsky psané soubory zvyšují průměrný počet kroků (o 3,84 kroku na úlohu) a náklady (o 19 %). Platíte o pětinu víc za mírně lepší výsledek.
Agenti instrukce dodržují, ale nepomáhá jim to
Důležité zjištění: agenti kontextové soubory neignorují. Když soubor zmíní konkrétní nástroj (např. uv místo pip, nebo specifický test runner), agenti ho skutečně použijí — v průměru 1,6× za úlohu oproti 0,01× bez kontextového souboru. Problém není v tom, že by agenti kontext ignorovali. Problém je v tom, že ten kontext nepomáhá vyřešit úlohu.
Přehledy architektury jsou zbytečné
Téměř 100 % LLM-generovaných a 67 % lidsky psaných kontextových souborů obsahuje přehled struktury repozitáře — adresáře, moduly, jak spolu souvisí. Intuitivně to dává smysl: agent se rychleji zorientuje. Data to ale nepotvrzují. Počet kroků, než agent poprvé interaguje s relevantním souborem, se s kontextovými soubory prakticky nemění. Agenti se k cíli nedostanou rychleji. Místo toho tráví víc času čtením a procházením repozitáře — dělají víc průzkumu, ale ne efektivnějšího.
Klíčový experiment: co se stane bez dokumentace
Nejzajímavější nález přišel, když autoři z repozitářů odstranili veškerou existující dokumentaci — README, docs/, docstringy, komentáře. V tomto režimu:
- LLM-generované kontextové soubory náhle začaly pomáhat— průměrné zlepšení +2,7 %
- V některých případech dokonce překonaly lidsky psané soubory
Interpretace je jasná: LLM-generované kontextové soubory jsou z velké části redundantní s existující dokumentací v repozitáři. Agent se totéž dozví z README a zdrojového kódu. Kontextový soubor mu řekne to samé ještě jednou — a agent stráví čas jeho zpracováním, aniž by získal novou informaci.
Silnější model neznamená lepší kontextový soubor
Autoři testovali generování kontextových souborů pomocí různých modelů (GPT-5.2, GPT-5.1 Mini, Claude Sonnet). Výsledek: kvalita generujícího modelu nemá konzistentní vliv na užitečnost výsledného souboru. Investice do dražšího modelu pro generování kontextu se nevyplácí.
Co funguje a co ne: praktická doporučení
Na základě studie a jejích dat:
Nedělejte:
- Negenerujte
AGENTS.mdautomaticky pomocí LLM a nepředpokládejte, že to pomůže. Data ukazují, že u dobře zdokumentovaných repozitářů to výkon spíš zhorší a náklady zvýší. - Nepište obsáhlé přehledy architektury a adresářové struktury. Agenti tuto informaci získají z kódu samotného a váš přehled jim nepomůže se zorientovat rychleji.
- Neduplikujte informace z README nebo docs/. Pokud je něco v README, nemusí to být v
AGENTS.md.
Dělejte:
- Pokud kontextový soubor píšete, zaměřte se na specifické, akční instrukce: jaký balíčkovací systém použít (
uv, nepip), jaký test runner spustit, jaké repo-specifické CLI nástroje existují. Tyto instrukce agenti prokazatelně dodržují. - U repozitářů se slabou nebo chybějící dokumentací může kontextový soubor pomoct — právě protože vyplňuje informační mezeru, kterou jinak agent nemá jak překlenout.
- Udržujte kontextové soubory krátké a konkrétní. Každý řádek, který agent zpracuje, stojí tokeny a potenciálně odvádí pozornost od řešení úlohy.
Claude Code do nových verzí přidal funkci memory.md, která automaticky ukládá do markdown souborů popisy API a jiné důležité informace, které by musel Code opakovaně analyzovat a zjišťovat. Více o tom, jak efektivně budovat dokumentaci projektu, najdete v článku o dokumentační strategii v Claude Code.
Limity studie
Studie má několik omezení, která je třeba mít na paměti:
Pouze Python. Všechny testované repozitáře jsou pythonové. Python je v trénovacích datech modelů masivně zastoupený, takže agenti ho zvládají i bez kontextu relativně dobře. U méně zastoupených jazyků (Rust, Elixir, Zig…) by kontextové soubory mohly mít větší přínos — ale to nevíme.
Pouze opravy bugů. SWE-bench i AGENTBENCH testují schopnost opravit existující bug. Neříkají nic o scénářích typu „implementuj nový feature od nuly” nebo „refaktoruj celý modul”, kde navigační kontext může hrát jinou roli.
Omezený rozsah. 138 instancí v AGENTBENCH a 300 v SWE-bench Lite je solidní, ale pro detekci malých efektů (řádově jednotky procent) není statistická síla obrovská.
Únor 2026. Agenti se rychle vyvíjejí. Výsledky platí pro testované verze Claude Code, Codex a Qwen Code. Budoucí agenti mohou kontext využívat efektivněji.
Závěr
Studie ukazuje, že moje puristické přesvědčení, že netřeba si do Claude Code přidávat hromadu přívěšků a doplnění, je v zásadě správné. Anthropic tento vývojářský nástroj rychle posouvá kupředu a veškerá zlepšení se snaží integrovat a vyhodnocovat jejich přínos. Takže pokud může přidat definiční sady ideálních postupů pro vývoj v nejrozšířenějších jazycích, udělal to - a asi to bude průběžně doplňovat. Příprava agentních souborů má smysl u legacy platforem, u specialitek. Současný hype kolem AGENTS.md a kontextových souborů není podložený daty. LLM-generované soubory v kontrolovaných testech výkon nezlepšují a zvyšují náklady. Lidsky psané soubory pomáhají mírně, ale jen pokud obsahují specifické, nezbytné instrukce — ne přehledy architektury.
Než strávíte odpoledne psaním dokonalého CLAUDE.md či AGENTS.md, zvažte, jestli váš čas nemá větší hodnotu jinde. A pokud ho přesto píšete, buďte struční a konkrétní. Rozhodně nemusíte zoufale vyhledávat ‘claude/agents.md’ soubory, které doporučují různé stránky, žádný smysl to nemá. Dříve možná přidávaly tyto soubory určitou vrstvu postupů, co dělat a jak postupovat, ale dnes už to daleko lépe vědí jednotliví vývojoví agenti sami o sobě a není třeba jim to explicitně vysvětlovat. Váš čas lépe investujete třeba do rozšíření funkcí pomocí pluginů pro Claude Code.
To mi připomíná, že jsem chtěl aktualizovat článek, jak vytvářet dobrý claude.md soubor pro Claude Code.