Když se dokumentace změní ve sběratelský projekt

Představ si tohle: začínáš nový projekt s čistým CLAUDE.md souborem. Pár užitečných rad. Několik poznámek pro kontext. Varování před tím zvláštním edge casem v autentizaci. O měsíce později ten soubor otevřřeš a je to tlustý román plný protichůdných instrukcí, zastaralých připomínek a zoufalých dodatků, které už nikdo pořádně nerozumí.

Tohle není jen tvůj problém. Je to univerzální jev.

Výzkum, který analyzoval 247 694 životních cyklů instrukcí napříč 1 867 repozitáři, odhalil znepokojivý vzor: agentické prompty nerosou jen — rostou bez jakýchkoli hranic, více než trojnásobně během své životnosti (+226 %). Průměrně tyto soubory získávají +4,9 čistých instrukcí s každým jedním commitem. Soubor se nikdy nezmenší. Jen roste.

Ale tady přichází ta opravdu zajímavá část: čím starší instrukce je, tím menší je pravděpodobnost, že bude smazána. Data ukazují log-hazard -0,032 na commit, což znamená, že instrukce se časem stávají čím dál tím nesmrtelnějšími. Ne že by nikdo nechtěl uklidit — jen nikdo neví, jestli může něco bezpečně odstranit.

Problém O(2^|D|)

Proč se tohle děje? Výzkumníci tomu říkají „katastrofální zapamatování" — inverzní problém k dobře známému „katastrofálnímu zapomínání" ve strojovém učení. Ale nepotřebuješ PhD, abys pochopil, proč se to děje.

Zamysli se nad kalkulací nákladů: přidání nové instrukce je levné. Vidíš problém, napíšeš opravu, jdeš dál. Okamžitá cena je nízká a vnímaný přínos jasný.

Ale odstranit instrukci? To je úplně jiná bestie. Musíš rozumět každému místu, kde by ta instrukce mohla hrát roli. Musíš promyslet interakce se všemi ostatními instrukcemi. Musíš ověřit, že její odstranění nezpůsobí něco subtlílního a důležitého. Výzkumníci vypočítali tyto kognitivní náklady jako O(2^|D|) v promptu s |D| instrukcemi — rostou tedy exponenciálně s počtem existujících instrukcí.

Takže vývojáři dělají to, co dělají racionální lidé: přestanou se o to snažit. Nové instrukce se připojují. Staré zůstávají. Soubor roste.

Komentáře: Nevyžádaný hrdina

Tady to začíná být opravdu vzrušující. Řešení nejsou lepší promptingové techniky ani chytřejší modely. Je to něco, co vývojáři používají od úsvitu programování: komentáře.

Výzkumníci zvolili zajímavý přístup — invertovali IFEval, standardní benchmark, aby vytvořili „ověřitelné světy", kde optimální prompty skutečně znali. Když přidali komentáře kódující latentní reasoning do promptů, nadměrný růst instrukcí klesl z +211,3 % na pouhých +1,4 %.

To je 99,3% redukce.

Ale ten pravý koláč na dortu? Tyto komentáře nejen kontrolovaly růst — zlepšily skutečný výkonfollowování instrukcí až o 23,1 % na reálných úkolech. Komentáře nejsou organizační balast. Jsou to nosné konstrukce, které pomáhají AI asistentům správně reasonovat o kontextu.

Proč to teď záleží

Žijeme v době fundamentální změny toho, co „kód" znamená. Výzkumníci kladou provokativní otázku: „Pokud je angličtina nový kód, proč ještě nemáme komentáře?"

Je to fér bod. Desítky let vývojáři chápali, že kód bez komentářů je technický dluh. Komentáře vysvětlují „proč", ne jen „co". Zachycují záměr, edge cases a institucionální znalosti, které se nedají odvodit ze syntaxe.

Přesto v naší štvanici předávat čím dál víc AI coding asistentům jsme zacházeli s přirozenými jazykovými instrukcemi, jako by byly něco jiného. Píšeme imperativy — udělej tohle, nedělej tamto, nezapomeň zkontrolovat X — bez vysvětlení našeho důvodu.

Výsledek je to, co vidíme v těch nafouknutých CLAUDE.md souborech: instrukce, kterým nikdo plně nerozumí, které si mohou odporovat, a které rostou bez jakéhokoli mechanismu racionalizace.

Cesta vpřed

Pokud spravuješ CLAUDE.md nebo podobný agentický prompt soubor, tady je to, co výzkum naznačuje:

1. Komentuj své instrukce, ne jen svůj kód. Vysvětli, proč pravidlo existuje. Zdokumentuj edge cases. Zachyť reasoning za rozhodnutími.

2. Přijmi periodickou racionalizaci. Nepouze připojuj — přepisuj. Výzkum výslovně zmiňuje, že kompletní přepisy jsou jednou z mála věcí, které růst zastaví.

3. Zacházej s AI instrukcemi jako s onboarding dokumentací. Předal bys novému vývojáři 400řádkový soubor neodlišených pravidel? Tvůj AI asistent si zaslouží stejnou přehlednost.

Trajektorie, na které jsme, není udržitelná. Každý nový projekt začíná s dobrými úmysly a končí nespravovatelným chaosem. Ale oprava možná je jednodušší, než jsme si mysleli: piš pro člověka (nebo AI), který bude tvé instrukce číst za šest měsíců, ne jen pro toho, kdo odpovídá na tvou otázku dnes.

Komentáře nejsou balast. Jsou to architektura porozumění.