--- title: "Pomáhají CLAUDE.md agentům? Překvapivě ne" description: "CLAUDE.md a AGENTS.md nepomáhají kodovacím agentům tak, jak se předpokládá. Studie to potvrzují. Jak zlepšit Claude Code soubory pro lepší výsledky?" date: 2026-02-27 author: "Patrick Zandl" url: https://www.vibecoding.cz/articles/claude-code/pomahaji-claude-md-a-agents-md-kodovacim-agentum-prekvapive-spis-ne/ --- > Markdown verze článku z Vibecoding.cz. HTML verze: https://www.vibecoding.cz/articles/claude-code/pomahaji-claude-md-a-agents-md-kodovacim-agentum-prekvapive-spis-ne/ > Přehled veškerého obsahu webu: https://www.vibecoding.cz/llms.txt # Pomáhají CLAUDE.md agentům? Překvapivě ne 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](https://www.vibecoding.cz/articles/claude-code/2025-08-14-claude_code_learning/). Kontextové soubory jako CLAUDE.md nebo AGENTS.md jsou v roce 2026 de facto standard pro agentní vývoj. Anthropic, OpenAI, [Cursor](https://www.vibecoding.cz/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](http://logicstar.ai/) (Maran, Schluntz, Tschannen & Vechev, únor 2026) provedli [první kontrolovaný experiment](https://arxiv.org/html/2602.11988v1). 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: 1. **Bez kontextového souboru** (baseline) 1. **S LLM-generovaným kontextovým souborem** — vygenerovaným z kódu repozitáře pomocí Claude Code a Codex 1. **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.md` automaticky 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`, ne `pip`), 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](https://www.vibecoding.cz/articles/claude-code/dokumentace-v-claude-code-strategie-ktera-funguje/). ## 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](https://www.vibecoding.cz/articles/claude-code/2025-10-09-claude-code-plugins/). To mi připomíná, že jsem chtěl aktualizovat článek, jak vytvářet dobrý `claude.md` soubor pro Claude Code.